---
title: "Get Audience"
method: GET
path: "/audiences"
tags: ["Audiences"]
---

# Get Audience

`GET /audiences`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/audiences`
- Auth: API key in header `PINNACLE-API-KEY`

Retrieve an audience by ID with optional pagination.

## Query parameters

- `id` string, required
- `page` integer
- `limit` integer

## Response `200`

Successfully retrieved audience.

- union
  - AudienceWithPagination
    - `id` string, required: Audience public ID. This identifier is a string that always begins with the prefix `aud_`, for example: `aud_abc123`.
    - `name` string, required: Audience name.
    - `description` string, required: Audience description.
    - `contacts` Contact[], required: Array of contact objects (paginated).
      - `description` string: Additional information about the contact.
      - `email` string: Contact's email address, if available.
      - `id` string, required: Unique ID of the contact. This identifier is a string that always begins with the prefix `co_`, for example: `co_1234567890`.
      - `name` string: Full name of the contact, if available.
      - `phoneNumber` string, required: Contact's phone number in E.164 format.
      - `tags` string[]: List of tags associated with the contact.
    - `contactCount` integer, required: Total number of contacts in audience.
    - `pagination` Pagination, required
      - `page` integer, required: Current page number (1-indexed).
      - `limit` integer, required: Items per page (max 100, default 50).
      - `total` integer, required: Total number of contacts in the audience.
      - `hasMore` boolean, required: Whether more pages exist.
  - AudienceCountOnly
    - `id` string, required: Audience public ID. This identifier is a string that always begins with the prefix `aud_`, for example: `aud_abc123`.
    - `name` string, required: Audience name.
    - `description` string, required: Audience description.
    - `contactCount` integer, required: Total number of contacts in audience. Use the [Get Audience](/api-reference/audiences/get) endpoint with the pagination parameters to get the audience with its contacts.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)