Skip to Content
API ReferenceAudiences

Audiences API

Audiences are named segmentation queries built on top of a parent entity model. They use a visual filter tree to define membership criteria based on properties, computed attributes, relationships, events, and other audiences.

Endpoints

MethodPathDescription
GET/api/v1/workspaces/{id}/audiencesList all audiences
POST/api/v1/workspaces/{id}/audiencesCreate an audience
GET/api/v1/workspaces/{id}/audiences/{audId}Get an audience
PUT/api/v1/workspaces/{id}/audiences/{audId}Update an audience
DELETE/api/v1/workspaces/{id}/audiences/{audId}Delete an audience
POST/api/v1/workspaces/{id}/audiences/archiveArchive up to 200 audiences
POST/api/v1/workspaces/{id}/audiences/{audId}/estimateEstimate audience size
POST/api/v1/workspaces/{id}/audiences/{audId}/compile-sqlCompile audience SQL (no execution)
GET/api/v1/workspaces/{id}/audiences/{audId}/previewPreview audience members
GET/api/v1/workspaces/{id}/models/{modelId}/audiencesList audiences by model
POST/api/v1/workspaces/{id}/models/{modelId}/estimate-filterEstimate filter count
POST/api/v1/workspaces/{id}/models/{modelId}/compile-filter-sqlCompile filter SQL (no execution)

List Audiences

GET /api/v1/workspaces/{id}/audiences

Returns all audiences in the workspace.

Response

[ { "id": "550e8400-e29b-41d4-a716-446655440000", "workspace_id": "660e8400-e29b-41d4-a716-446655440000", "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "name": "High-Value Customers", "description": "Customers with lifetime value over $1000", "filter_tree": { "type": "and", "children": [ { "type": "condition", "condition_type": "property", "column": "lifetime_value", "operator": "greater_than", "value": 1000 } ] }, "estimated_size": 4250, "estimated_at": "2024-01-15T15:00:00Z", "status": "active", "status_error": "", "identity_graph_id": null, "sync_health": { "state": "failing", "total": 3, "healthy": 1, "warning": 0, "failing": 1, "paused": 1, "last_error": "Destination returned 401 Unauthorized" }, "created_by": "880e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z" } ]

Sync health

The list (and only the list) adds sync_health: a summary of every sync connected to the audience, batch and realtime.

  • state is failing if any sync is failing, otherwise warning if any needs attention, otherwise healthy if the audience has any sync, otherwise none.
  • paused counts syncs a person paused. They do not affect state. A sync paused automatically after repeated failures counts as failing.
  • last_error is the error from the most recently failing sync, or empty.
  • The field is omitted when the caller can read audiences but not syncs (syncs.read).

Example

curl -X GET https://agentic.zeotap.com/api/v1/workspaces/{id}/audiences \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

Create Audience

POST /api/v1/workspaces/{id}/audiences

Creates a new audience with a filter tree definition.

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name
descriptionstringNoDescription
parent_model_idstring (UUID)YesParent entity model the audience is built on
filter_treeobjectYesRecursive filter tree definition
identity_graph_idstring (UUID)NoIdentity graph for cross-model resolution

Filter Tree Structure

The filter tree is a recursive JSON structure that supports boolean logic (and, or, not) and multiple condition types.

Group Nodes

{ "type": "and", "children": [...] }
TypeDescription
andAll children must match
orAt least one child must match
notNegates the child condition

Property Condition

Filters on a column of the parent model.

{ "type": "condition", "condition_type": "property", "column": "lifetime_value", "operator": "greater_than", "value": 1000 }

Computed Attribute Condition

Filters on a computed attribute value. (The condition_type value remains trait for backwards compatibility.)

{ "type": "condition", "condition_type": "trait", "trait_id": "550e8400-e29b-41d4-a716-446655440000", "operator": "greater_than", "value": 5 }

Relation Condition

Filters based on related model records, with optional nested filters.

{ "type": "condition", "condition_type": "relation", "relationship_id": "660e8400-e29b-41d4-a716-446655440000", "quantifier": "any", "count_operator": "at_least", "count_value": 1, "filters": { "type": "and", "children": [ { "type": "condition", "condition_type": "property", "column": "category", "operator": "equals", "value": "electronics" } ] } }

Event Condition

Filters based on event occurrences with time windows.

{ "type": "condition", "condition_type": "event", "relationship_id": "770e8400-e29b-41d4-a716-446655440000", "count_operator": "at_least", "count_value": 3, "time_window": { "type": "within", "value": 30, "unit": "days" } }

Audience Condition

Filters based on membership in another audience.

{ "type": "condition", "condition_type": "audience", "audience_id": "880e8400-e29b-41d4-a716-446655440000", "operator": "is_member" }

Operators

OperatorApplicable TypesDescription
equalstext, numberExact match
not_equalstext, numberNot equal
greater_thannumber, timestampGreater than
less_thannumber, timestampLess than
greater_than_or_equalnumber, timestampGreater than or equal
less_than_or_equalnumber, timestampLess than or equal
containstextSubstring match
not_containstextDoes not contain
starts_withtextPrefix match
ends_withtextSuffix match
is_nullanyValue is null
is_not_nullanyValue is not null
intext, numberValue is in list
not_intext, numberValue is not in list
betweennumber, timestampValue is between two bounds
is_memberaudienceMember of audience
is_not_memberaudienceNot a member of audience

Count Operators (for relation/event conditions)

OperatorDescription
at_leastCount >= value
at_mostCount <= value
exactlyCount == value
betweencount_value <= count <= count_value2 (both inclusive; event conditions only)

Time Window (for event conditions)

FieldTypeDescription
typestringwithin, not_within, before, after, between, or one of the event range shapes relative_range, date_range, before_date
valueintegerTime amount (for relative_range, how long ago the range starts)
unitstringhours, days, weeks, months
end_valueintegerrelative_range only: how long ago the range ends (0 = now)
end_unitstringrelative_range only: unit of end_value
start_datestringdate_range only: first day counted, YYYY-MM-DD
end_datestringdate_range: last day counted (inclusive); before_date: matches strictly before this day. YYYY-MM-DD

Full Example

curl -X POST https://agentic.zeotap.com/api/v1/workspaces/{id}/audiences \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>" \ -H "Content-Type: application/json" \ -d '{ "name": "High-Value Recent Buyers", "description": "Customers with LTV > $1000 who purchased in the last 30 days", "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "filter_tree": { "type": "and", "children": [ { "type": "condition", "condition_type": "property", "column": "lifetime_value", "operator": "greater_than", "value": 1000 }, { "type": "condition", "condition_type": "event", "relationship_id": "990e8400-e29b-41d4-a716-446655440000", "count_operator": "at_least", "count_value": 1, "time_window": { "type": "within", "value": 30, "unit": "days" } } ] } }'

Get Audience

GET /api/v1/workspaces/{id}/audiences/{audId}

Returns a single audience by ID.

Example

curl -X GET https://agentic.zeotap.com/api/v1/workspaces/{id}/audiences/{audId} \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

Update Audience

PUT /api/v1/workspaces/{id}/audiences/{audId}

Updates an existing audience definition.

Request Body

Same fields as create. Only include fields you want to change.


Delete Audience

DELETE /api/v1/workspaces/{id}/audiences/{audId}

Deletes an audience. Cannot be deleted if active syncs reference it.

Response

{ "status": "deleted" }

Archive Audiences

POST /api/v1/workspaces/{id}/audiences/archive

Archives up to 200 audiences in one request. Requires audiences.write. Each audience is archived exactly as an edit to "status": "archived" would archive it, and gets its own audit-log entry.

Archiving stops an audience’s realtime evaluation. It cannot be activated, and the Membership API no longer serves it. Archiving does not stop its batch syncs or the orchestrations that enter on it; pause those separately. To restore an audience, update its status back to draft or active.

Request Body

{ "audience_ids": ["550e8400-e29b-41d4-a716-446655440000", "551e8400-e29b-41d4-a716-446655440000"] }

Response

One result per distinct id, in request order. A failure on one audience does not fail the others.

{ "results": [ { "audience_id": "550e8400-e29b-41d4-a716-446655440000", "outcome": "archived", "message": "" }, { "audience_id": "551e8400-e29b-41d4-a716-446655440000", "outcome": "skipped", "message": "Already archived." } ] }

outcome is archived, skipped (already archived; nothing changed) or failed, with the reason in message. An empty or missing list returns 400 with code audience_ids_required; more than 200 ids returns 400 with code too_many_audience_ids.


Estimate Audience Size

POST /api/v1/workspaces/{id}/audiences/{audId}/estimate

Runs the audience’s filter query against the warehouse to count matching records. The result is saved to the audience’s estimated_size and estimated_at fields.

Response

{ "estimated_size": 4250, "estimated_at": "2024-01-15T15:00:00Z" }

Example

curl -X POST https://agentic.zeotap.com/api/v1/workspaces/{id}/audiences/{audId}/estimate \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

Compile Audience SQL

POST /api/v1/workspaces/{id}/audiences/{audId}/compile-sql

Returns the SQL the estimate would run — without running it. Everything the estimate does is done except the execution: permissions, canvas resolution, subset enforcement, relationship / trait / nested-audience resolution, identity-graph joins and canvas post-processors all apply, so count_sql is byte-for-byte the query POST .../estimate sends to the warehouse.

Because nothing is executed, this endpoint works even when the warehouse is unreachable, and it never reads or writes the estimate cache, the audience’s estimated_size, or its size history. Requires audiences.read.

Response

FieldTypeDescription
audience_idstring (UUID)The compiled audience
parent_model_idstring (UUID)Parent entity model the SQL reads
source_idstring (UUID)Source the SQL would run against
source_typestringe.g. snowflake, bigquery, databricks, clickhouse
dialectstringSQL dialect the query was compiled for
count_sqlstringThe COUNT query the estimate executes
member_sqlstringThe member row query syncs and previews execute
statusstringcompiled
{ "audience_id": "550e8400-e29b-41d4-a716-446655440000", "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "source_id": "990e8400-e29b-41d4-a716-446655440000", "source_type": "snowflake", "dialect": "snowflake", "count_sql": "SELECT COUNT(*) AS cnt FROM (SELECT parent.* FROM (SELECT * FROM customers) parent WHERE parent.\"lifetime_value\" > 1000) _count_inner", "member_sql": "SELECT parent.* FROM (SELECT * FROM customers) parent WHERE parent.\"lifetime_value\" > 1000", "status": "compiled" }

Example

curl -X POST https://agentic.zeotap.com/api/v1/workspaces/{id}/audiences/{audId}/compile-sql \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

Preview Audience Members

GET /api/v1/workspaces/{id}/audiences/{audId}/preview

Returns a sample of records that match the audience’s filter criteria.

Response

{ "columns": [ {"name": "customer_id", "type": "VARCHAR", "nullable": false}, {"name": "email", "type": "VARCHAR", "nullable": true} ], "rows": [ {"customer_id": "C001", "email": "alice@example.com"}, {"customer_id": "C002", "email": "bob@example.com"} ] }

List Audiences by Model

GET /api/v1/workspaces/{id}/models/{modelId}/audiences

Returns all audiences attached to a specific parent model.


Estimate Filter

POST /api/v1/workspaces/{id}/models/{modelId}/estimate-filter

Estimates the count of matching records for an ad-hoc filter tree without creating an audience. Useful for the audience builder UI to show real-time size estimates.

Request Body

FieldTypeRequiredDescription
filter_treeobjectYesFilter tree to evaluate

Response

{ "estimated_size": 3200 }

Compile Filter SQL

POST /api/v1/workspaces/{id}/models/{modelId}/compile-filter-sql

The compile-only twin of Estimate Filter: takes the same body and returns the SQL an ad-hoc filter tree compiles to, without running it. The tree is canonicalized and validated exactly as the estimate would, so a tree that compiles here compiles there.

Request Body

FieldTypeRequiredDescription
filter_treeobjectYesFilter tree to compile
identity_graph_idstring (UUID)NoIdentity graph to resolve members through

Response

Same shape as Compile Audience SQL, without audience_id.

{ "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "source_id": "990e8400-e29b-41d4-a716-446655440000", "source_type": "snowflake", "dialect": "snowflake", "count_sql": "SELECT COUNT(*) AS cnt FROM (SELECT parent.* FROM (SELECT * FROM customers) parent WHERE parent.\"plan\" = 'pro') _count_inner", "member_sql": "SELECT parent.* FROM (SELECT * FROM customers) parent WHERE parent.\"plan\" = 'pro'", "status": "compiled" }

Audience Object

FieldTypeDescription
idstring (UUID)Unique identifier
workspace_idstring (UUID)Owning workspace
parent_model_idstring (UUID)Parent entity model
namestringDisplay name
descriptionstringDescription
filter_treeobjectRecursive filter tree definition
estimated_sizeinteger or nullLast estimated member count
estimated_atstring (ISO 8601) or nullWhen size was last estimated
statusstringdraft, active, archived, error, or broken
broken_reasonobject or nullPresent while status is broken: what was lost, and why
status_errorstringError message when status is error
identity_graph_idstring (UUID) or nullOptional identity graph for cross-model resolution
created_bystring (UUID)Account that created the audience
created_atstring (ISO 8601)Creation timestamp
updated_atstring (ISO 8601)Last update timestamp
Last updated on