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

# Get audiences

`GET /v1/audiences`

Unified audience read. Omit `audienceId` to LIST the brand’s saved audiences under `{ data, pagination }`. Each row carries its contact `filters`, the cached member `count`, and ISO timestamps. An audience is the recipient target for `POST /v1/sends`. Pass `?audienceId=` to fetch ONE — returns `{ data: [row] }` (no `pagination`), `404 AUDIENCE_NOT_FOUND` on an unknown / cross-brand id. Add `?include=count` (detail only) to replace the cached `count` with a freshly computed member total.

## Query parameters

- `audienceId` string
- `include` 'count'
- `limit` integer
- `cursor` string

## Response `200`

A page of audiences (list mode), or `{ data: [row] }` (detail mode).

- AudiencesListResponse
  - `data` object[], required
    - `audienceId` string, required
    - `audienceName` string, required
    - `filters` object, required
      - `filters` object[], required
        - `field` string, required
        - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'contains_any' | 'not_contains_any' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'is_true' | 'is_false' | 'in' | 'not_in' | 'is_empty' | 'not_exists' | 'is_not_empty' | 'exists' | 'is_set' | 'before' | 'after' | 'on_date', required
        - `value` unknown
        - `type` string — The field's value type — set `number`, `date`, or `boolean` for typed comparisons (dates are stored as epoch-ms, so a string `equals` on a date never matches). Omit for plain string fields.
      - `logicalOperator` 'and' | 'or', required
    - `count` integer, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `pagination` object
    - `limit` integer, required
    - `cursor` string, nullable, required
    - `hasMore` boolean, required

## Other responses

- `400` — The request body or query string was invalid (unknown key, wrong type, or missing required field). Strict schemas reject unknown keys — including `brandId`, which is always resolved from the API key.
- `401` — The API key was missing, invalid, or revoked.
- `403` — The caller does not have the required `audiences` permission.
- `404` — Audience not found in the API-key brand. Cross-brand ids intentionally surface as 404 (never 403) so the API does not leak cross-brand existence.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.

---

[API](https://skmtc.net/brew/apis/brew-public-api-v1.md) · [All operations](https://skmtc.net/brew/apis/brew-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brew/brew-public-api-v1/revisions/db96cfedc6c5/schema)