> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Audiences

> Retrieve all audiences for your account with optional filtering and pagination.

Returns a paginated list of audiences belonging to your account.

## Query Parameters

<ParamField query="status" type="string" default="active">
  Filter audiences by status. Accepted values: `active`, `archived`.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  Page number for pagination.
</ParamField>

<ParamField query="per_page" type="integer" default={50}>
  Number of audiences per page. Maximum: `100`.
</ParamField>

## Response Fields

<ResponseField name="audiences" type="array">
  Array of audience objects.

  <Expandable title="Audience object properties">
    <ResponseField name="id" type="string">
      Unique audience identifier.
    </ResponseField>

    <ResponseField name="name" type="string">
      Audience name.
    </ResponseField>

    <ResponseField name="description" type="string">
      Audience description.
    </ResponseField>

    <ResponseField name="source_lists" type="array of integers">
      Sending list IDs this audience is scoped to. Empty array means all lists.
    </ResponseField>

    <ResponseField name="filter" type="object">
      Filter group definition. See [Audience Filter DSL](/api-reference/v2/audience-filter-dsl) for structure. Filter condition objects use camelCase keys (e.g. `conditionType`, `listId`).
    </ResponseField>

    <ResponseField name="cached_size" type="integer">
      Most recently calculated audience size.
    </ResponseField>

    <ResponseField name="cached_size_updated_at" type="datetime">
      Timestamp when `cached_size` was last calculated.
    </ResponseField>

    <ResponseField name="status" type="string">
      Audience status: `active` or `archived`.
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the audience was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination object properties">
    <ResponseField name="page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      Number of items per page.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of audiences matching the filter.
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
      Total number of pages.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25" \
    -H "X-Api-Key: trk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.tracklysms.com/api/v2/audiences",
      headers={"X-Api-Key": "trk_your_api_key_here"},
      params={"status": "active", "page": 1, "per_page": 25}
  )

  data = response.json()
  for audience in data["audiences"]:
      print(f"{audience['name']} — {audience['cached_size']} contacts")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25",
    {
      headers: { "X-Api-Key": "trk_your_api_key_here" },
    }
  );

  const data = await response.json();
  data.audiences.forEach((audience) => {
    console.log(`${audience.name} — ${audience.cached_size} contacts`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "audiences": [
      {
        "id": "664f1a2b3c4d5e6f7a8b9c0d",
        "name": "High-Value Clickers",
        "description": "Contacts who clicked at least 3 times in the last 30 days",
        "source_lists": [101, 102],
        "filter": {
          "operator": "AND",
          "conditions": [
            {
              "conditionType": "time",
              "field": "last_clicked_at",
              "operator": "within",
              "value": 30,
              "unit": "days",
              "listId": null
            },
            {
              "conditionType": "count",
              "field": "click_count",
              "operator": "gte",
              "value": 3,
              "unit": null,
              "listId": null
            }
          ],
          "groups": []
        },
        "cached_size": 12480,
        "cached_size_updated_at": "2025-11-15T08:30:00",
        "status": "active",
        "created_at": "2025-10-01T14:22:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 1,
      "total_pages": 1
    }
  }
  ```

  ```json 401 — Unauthorized theme={null}
  {
    "error": "Invalid credentials",
    "code": "invalid_credentials"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code            | Description                                                                |
| ----------- | --------------------- | -------------------------------------------------------------------------- |
| 401         | `invalid_credentials` | API key is missing or invalid                                              |
| 403         | `account_suspended`   | Your account is suspended. Resolve outstanding billing or contact support. |
| 429         | `rate_limited`        | Request throttled; retry with exponential backoff after the window resets. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Audiences" icon="users" href="/guides/audiences/creating-audiences">
    Build audiences in the UI
  </Card>

  <Card title="Create Schedule" icon="calendar" href="/api-reference/v2/schedules/create-schedule">
    Schedule a campaign to an audience
  </Card>
</CardGroup>