Sign in
Audiences

List Audiences

List custom and lookalike audiences for an account. Pass audience_id to return a specific audience.

get/audiences

Query parameters

account_idstring required

Account ID, prefixed biz_.

audience_idstring

Audience ID, prefixed adaud_, used to filter the response to one audience.

audience_type'custom' | 'lookalike'

Filter by custom or lookalike audiences.

source_type'csv_upload' | 'people_filter' | 'engagement'

Filter by uploaded customer lists, Whop People filters, or social engagement.

firstinteger

Number of results to return from the start of the range.

afterstring

Return results after this cursor. Use page_info.end_cursor from the previous response to fetch the next page.

Response

Audiences listed.

Example response

{
  "data": [
    {
      "audience_type": "lookalike",
      "created_at": "2026-01-01T12:00:00.000Z",
      "engagement": {
        "exclude": [
          {
            "event": "watched_50_percent",
            "object": "video",
            "platform_video_ids": [
              "444"
            ],
            "retention_days": 30,
            "social_account_id": "sacc_xxxxxxxxxxxxxx"
          }
        ],
        "include": [
          {
            "event": "watched_50_percent",
            "object": "video",
            "platform_video_ids": [
              "444"
            ],
            "retention_days": 30,
            "social_account_id": "sacc_xxxxxxxxxxxxxx"
          }
        ],
        "platform": "meta"
      },
      "error_message": "412 of 1,000 rows had no email or phone number, so the list could not be matched.",
      "filters": {
        "country": "US",
        "last_seen_within_days": 30
      },
      "id": "adaud_xxxxxxxxxxxxxx",
      "last_refreshed_at": "2026-01-01T12:00:00.000Z",
      "lookalike_ratio": 0.04,
      "lookalike_starting_ratio": 0.02,
      "match_rates": [
        {
          "lower_bound": 40,
          "platform": "meta",
          "status": "available",
          "upper_bound": 50
        }
      ],
      "name": "Past purchasers Lookalike 2–4%",
      "platform_audience_ids": [
        "120246230799130687"
      ],
      "source_audience_id": "adaud_xxxxxxxxxxxxxx",
      "source_type": "csv_upload",
      "updated_at": "2026-01-01T12:00:00.000Z"
    }
  ],
  "page_info": {
    "start_cursor": "WyJjdXJzb3IiLDFd"
  }
}

Changes

Changed in 5 of the 74 revisions of this API.3215

  • ff3a7657356311See the full diff
    • ▲

      for the query request parameter first, default value 20 was added

      request-parameter-default-value-added

    • ●

      for the query request parameter first, the max was set to 100.00

      request-parameter-max-set

  • 4fe3b2d2154613See the full diff
    • ●

      added the new engagement enum value to the // response property for the response status

      response-property-enum-value-added

    • ○

      added the new optional header request parameter Api-Version-Date to all path's operations

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new enum value engagement to the query request parameter source_type

      request-parameter-enum-value-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • f1020c3ecda41See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 60bbb4a6ffbc10See the full diff
    • ○

      added the new optional query request parameter audience_type

      new-optional-request-parameter

    • ○

      added the new optional query request parameter source_type

      new-optional-request-parameter

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3a06a605784b21See the full diff
    • ▲

      the // response's property type changed from number to string for status

      response-property-type-changed

    • ▲

      the // response's property type changed from number to string for status

      response-property-type-changed

    • ○

      added the required property // to the response with the status

      response-required-property-added

Of the 74 revisions, 1 has no diff computed.