Audiences API

The audiences API lets you query audience segments programmatically. Use it to check whether a user belongs to a segment, list segment members, or get member counts.

Check membership

Check whether a specific user is a member of an audience segment.

GET /v1/api/audiences/:id/check?user_id=user_123

Auth: Secret key required

URL parameters: :id is the audience/segment ID.

Query parameters:

Param	Required	Description
`user_id`	Yes	The user ID to check

Response 200:

{ "match": true }

Returns { "match": false } if the user is not in the segment.

Errors:

Status	Error
`400`	`user_id query parameter is required`
`404`	`Audience not found`

List members

List user IDs currently in an audience segment. Membership is evaluated against ClickHouse event data at query time.

GET /v1/api/audiences/:id/users

Auth: Secret key required

URL parameters: :id is the audience/segment ID.

Query parameters:

Param	Default	Max	Description
`limit`	100	1000	Number of users to return

Response 200:

{
  "users": ["user_123", "user_456", "user_789"],
  "count": 3
}

Errors:

Status	Error
`404`	`Audience not found`

Count members

Get the total count of users currently in an audience segment.

GET /v1/api/audiences/:id/count

Auth: Secret key required

URL parameters: :id is the audience/segment ID.

Response 200:

{ "count": 1247 }

Errors:

Status	Error
`404`	`Audience not found`