Audiences API

Preview audience segment definitions before materializing them. The Audiences API lets you test a segment's reach and inspect sample records in real time — without creating a persistent audience in the CDP.

Base URL: https://api.experiture.ai/public/v1

Authentication: All endpoints require a bearer token with cdp:audiences:preview scope. See Authentication.

Overview

Operation	Endpoint	Mode	Use Case
Preview audience	`POST /audiences/{audience_id}/preview`	Synchronous	Run an audience definition and see match count + sample rows.

Preview runs against live data and executes the same query engine used for materialized audiences, so counts and sample rows are authoritative.

Preview an Audience

Execute an existing audience definition and return its current match count plus a sample of records. Useful for:

Validation — confirm a segment returns the expected cohort before activating it.
Campaign sizing — get an up-to-the-second reach estimate.
Debugging — inspect actual records that match (or don't match) a rule.

POST /audiences/{audience_id}/preview
Authorization: Bearer <token>
Content-Type: application/json

Path parameters

Name	Type	Description
`audience_id`	string	ID of the saved audience definition.

Request body

Field	Type	Required	Description
`limit`	integer	No	Max sample records to return. Range `1 – 1000`. Default `100`.

Example request

curl -X POST https://api.experiture.ai/public/v1/audiences/aud_01HXYZ/preview \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 50 }'

Response — 200 OK

{
  "success": true,
  "data": {
    "audienceId": "aud_01HXYZ",
    "matchCount": 18432,
    "isExact": true,
    "executionTimeMs": 412,
    "fieldsUsed": ["email", "tier", "last_order_at", "country"],
    "sampleRecords": [
      {
        "email": "jane@example.com",
        "tier": "gold",
        "country": "US",
        "last_order_at": "2026-04-20T12:00:00Z"
      }
    ]
  },
  "correlationId": "<uuid>"
}

Response Fields

Field	Type	Description
`audienceId`	string	Echo of the path parameter.
`matchCount`	integer	Total rows matching the audience definition.
`isExact`	boolean	`true` if the count is exact; `false` if it is an approximation. Defaults to `false`.
`executionTimeMs`	integer	Server-side query execution time.
`fieldsUsed`	array	Columns referenced by the audience rules. Useful for understanding dependencies.
`sampleRecords`	array	Up to `limit` matching records (projected to `fieldsUsed`).

Errors

HTTP Status	Code	Meaning
`400`	`CDP_ETL.VALIDATION.REQUEST_INVALID`	`limit` out of range or body malformed.
`401`	`CDP_ETL.AUTH.UNAUTHORIZED`	Missing or invalid bearer token.
`403`	`CDP_ETL.AUTH.FORBIDDEN`	Token lacks read access to the audience.
`404`	`CDP_ETL.AUDIENCE.NOT_FOUND`	No audience exists with the given `audience_id` in this workspace.
`422`	`CDP_ETL.AUDIENCE.INVALID`	The audience definition references fields that no longer exist.
`429`	`CDP_ETL.RATE.LIMITED`	See Rate Limits.

Constraints

Execution budget: previews are capped at ~30 s server-side. Very complex audiences may time out — simplify or materialize.
Sample size: limit caps at 1,000. For full exports, materialize the audience and use an export job.
Read-your-writes: profile writes are reflected in preview within seconds of acceptance (no need to wait for batch merge).