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

# List Audiences

`GET /audiences`

Lists uploaded customer-list audiences for an account. Pass `audience_id` to return a specific audience.

## Query parameters

- `account_id` string, required
- `audience_id` string
- `audience_type` 'custom' | 'lookalike'
- `source_type` 'csv_upload' | 'people_filter'
- `first` integer
- `after` string

## Response `200`

Audiences listed.

- object
  - `data` Audience[], required
    - `audience_type` 'custom' | 'lookalike', required — `custom` = a customer list (uploaded, or built from saved People filters); `lookalike` = Meta lookalike built from a custom audience.
    - `auto_refresh` boolean, required — Whether membership keeps updating. `true` rebuilds it from the saved filters twice a day, so people join and leave as they start and stop matching. `false` keeps whoever matched when it was built and never rebuilds. Always `false` for uploaded lists and lookalikes.
    - `created_at` string, required — When the audience was created, as an ISO 8601 timestamp.
    - `error_message` string, nullable, required — Processing error message. `null` unless processing is partial or failed.
    - `filters` object, nullable, required — For audiences built from People filters: the filters that define membership, keyed exactly as `GET /people` accepts them — for example `{"os": "iOS", "country": "US"}`. `null` for uploaded lists and lookalikes.
    - `id` string, required — Audience ID, prefixed `adaud_`.
    - `last_refreshed_at` string, nullable, required — When the audience membership was last rebuilt, as an ISO 8601 timestamp. `null` until the first build completes.
    - `lookalike_ratio` number, nullable, required — For lookalikes: the upper bound of the similarity band as a fraction (0.02 = top 2%). `null` for custom audiences.
    - `lookalike_starting_ratio` number, nullable, required — For lookalikes: the lower bound of the similarity band as a fraction. `null` for custom audiences and first-tier lookalikes.
    - `match_rates` AudienceMatchRate[], required
      - `lower_bound` number, nullable, required — Lower bound of the estimated match rate percentage. `null` until available.
      - `platform` 'meta', required — The ad platform that provided the match-rate estimate.
      - `status` 'calculating' | 'available' | 'unavailable' | 'null', nullable, required — Availability of the estimated match rate.
      - `upper_bound` number, nullable, required — Upper bound of the estimated match rate percentage. `null` until available.
    - `matched_rows` number, required — Members successfully uploaded to connected ad accounts. Always 0 for lookalikes.
    - `name` string, required — Audience display name.
    - `platform_audience_ids` string[], required
    - `processed_rows` number, required — Members processed from the source so far. Always 0 for lookalikes.
    - `progress_percent` number, required — Processing progress from 0 to 100.
    - `source_audience_id` string, nullable, required — For lookalikes: the audience this lookalike was built from. `null` for custom audiences.
    - `source_type` 'csv_upload' | 'people_filter', required — Where members come from. `csv_upload` = an uploaded customer list; `people_filter` = built from saved People filters. See `auto_refresh` for whether a `people_filter` audience keeps updating.
    - `status` 'pending' | 'processing' | 'syncing' | 'ready' | 'partial' | 'failed', required — Current state of the audience import. `syncing` means Whop is sending matched rows to connected ad accounts. When status is `partial` or `failed`, `error_message` explains what went wrong.
    - `total_rows` number, required — Total members detected in the source — CSV rows for uploaded lists, matching people for automatic audiences. Always 0 for lookalikes.
    - `updated_at` string, required — When the audience was last updated, as an ISO 8601 timestamp.
  - `page_info` object, required
    - `end_cursor` string, nullable, required
    - `has_next_page` boolean, required
    - `has_previous_page` boolean, required
    - `start_cursor` string, nullable, required

## Other responses

- `401` — Unauthorized

---

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