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

> Calculate the current size of an audience in real time.

Calculates the current number of contacts matching the audience's filter in real time. This operation runs the filter query against your contact database and updates the audience's `cached_size` and `cached_size_updated_at` fields.

<Warning>
  Size calculations run in real time against your contact database. For audiences with complex filters or large contact lists, this may take several seconds to complete.
</Warning>

## Path Parameters

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

## Response Fields

<ResponseField name="audience_id" type="string">
  The audience ID that was calculated.
</ResponseField>

<ResponseField name="size" type="integer">
  The current number of contacts matching the audience filter.
</ResponseField>

<ResponseField name="calculated_at" type="datetime">
  Timestamp when the calculation was performed.
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d/size" \
    -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}/size",
      headers={"X-Api-Key": "trk_your_api_key_here"},
  )

  data = response.json()
  print(f"Audience size: {data['size']} contacts (as of {data['calculated_at']})")
  ```

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

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

  const data = await response.json();
  console.log(`Audience size: ${data.size} contacts (as of ${data.calculated_at})`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "audience_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "size": 12480,
    "calculated_at": "2025-11-20T10:30:45"
  }
  ```

  ```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">
    Build and size audiences
  </Card>

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