> ## 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.

# Get Audience

> Retrieve a single audience by its ID.

Returns the full audience object for the specified ID, including its filter definition and cached size.

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the audience.
</ParamField>

## Response Fields

<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. Note: filter condition objects use camelCase keys (e.g. `conditionType`, `listId`).
</ResponseField>

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

<ResponseField name="cached_size_updated_at" type="datetime">
  Timestamp when `cached_size` was last calculated. `null` if never 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>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
    -H "X-Api-Key: trk_your_api_key_here"
  ```

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

  audience_id = "664f1a2b3c4d5e6f7a8b9c0d"

  response = requests.get(
      f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
      headers={"X-Api-Key": "trk_your_api_key_here"},
  )

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

  ```javascript Node.js theme={null}
  const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";

  const response = await fetch(
    `https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
    {
      headers: { "X-Api-Key": "trk_your_api_key_here" },
    }
  );

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

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "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"
  }
  ```

  ```json 404 — Not Found theme={null}
  {
    "error": "Audience not found",
    "code": "not_found"
  }
  ```

  ```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. |
| 404         | `not_found`           | No audience exists with the specified ID                                   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Audiences" icon="users" href="/guides/audiences/creating-audiences">
    Learn about audience segments
  </Card>

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