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
| Method | Path | Description |
|---|---|---|
GET | /api/v1/workspaces/{id}/audiences | List all audiences |
POST | /api/v1/workspaces/{id}/audiences | Create 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/archive | Archive up to 200 audiences |
POST | /api/v1/workspaces/{id}/audiences/{audId}/estimate | Estimate audience size |
POST | /api/v1/workspaces/{id}/audiences/{audId}/compile-sql | Compile audience SQL (no execution) |
GET | /api/v1/workspaces/{id}/audiences/{audId}/preview | Preview audience members |
GET | /api/v1/workspaces/{id}/models/{modelId}/audiences | List audiences by model |
POST | /api/v1/workspaces/{id}/models/{modelId}/estimate-filter | Estimate filter count |
POST | /api/v1/workspaces/{id}/models/{modelId}/compile-filter-sql | Compile 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.
stateisfailingif any sync is failing, otherwisewarningif any needs attention, otherwisehealthyif the audience has any sync, otherwisenone.pausedcounts syncs a person paused. They do not affectstate. A sync paused automatically after repeated failures counts asfailing.last_erroris 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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name |
description | string | No | Description |
parent_model_id | string (UUID) | Yes | Parent entity model the audience is built on |
filter_tree | object | Yes | Recursive filter tree definition |
identity_graph_id | string (UUID) | No | Identity 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": [...]
}| Type | Description |
|---|---|
and | All children must match |
or | At least one child must match |
not | Negates 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
| Operator | Applicable Types | Description |
|---|---|---|
equals | text, number | Exact match |
not_equals | text, number | Not equal |
greater_than | number, timestamp | Greater than |
less_than | number, timestamp | Less than |
greater_than_or_equal | number, timestamp | Greater than or equal |
less_than_or_equal | number, timestamp | Less than or equal |
contains | text | Substring match |
not_contains | text | Does not contain |
starts_with | text | Prefix match |
ends_with | text | Suffix match |
is_null | any | Value is null |
is_not_null | any | Value is not null |
in | text, number | Value is in list |
not_in | text, number | Value is not in list |
between | number, timestamp | Value is between two bounds |
is_member | audience | Member of audience |
is_not_member | audience | Not a member of audience |
Count Operators (for relation/event conditions)
| Operator | Description |
|---|---|
at_least | Count >= value |
at_most | Count <= value |
exactly | Count == value |
between | count_value <= count <= count_value2 (both inclusive; event conditions only) |
Time Window (for event conditions)
| Field | Type | Description |
|---|---|---|
type | string | within, not_within, before, after, between, or one of the event range shapes relative_range, date_range, before_date |
value | integer | Time amount (for relative_range, how long ago the range starts) |
unit | string | hours, days, weeks, months |
end_value | integer | relative_range only: how long ago the range ends (0 = now) |
end_unit | string | relative_range only: unit of end_value |
start_date | string | date_range only: first day counted, YYYY-MM-DD |
end_date | string | date_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
| Field | Type | Description |
|---|---|---|
audience_id | string (UUID) | The compiled audience |
parent_model_id | string (UUID) | Parent entity model the SQL reads |
source_id | string (UUID) | Source the SQL would run against |
source_type | string | e.g. snowflake, bigquery, databricks, clickhouse |
dialect | string | SQL dialect the query was compiled for |
count_sql | string | The COUNT query the estimate executes |
member_sql | string | The member row query syncs and previews execute |
status | string | compiled |
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
filter_tree | object | Yes | Filter 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
| Field | Type | Required | Description |
|---|---|---|---|
filter_tree | object | Yes | Filter tree to compile |
identity_graph_id | string (UUID) | No | Identity 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
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier |
workspace_id | string (UUID) | Owning workspace |
parent_model_id | string (UUID) | Parent entity model |
name | string | Display name |
description | string | Description |
filter_tree | object | Recursive filter tree definition |
estimated_size | integer or null | Last estimated member count |
estimated_at | string (ISO 8601) or null | When size was last estimated |
status | string | draft, active, archived, error, or broken |
broken_reason | object or null | Present while status is broken: what was lost, and why |
status_error | string | Error message when status is error |
identity_graph_id | string (UUID) or null | Optional identity graph for cross-model resolution |
created_by | string (UUID) | Account that created the audience |
created_at | string (ISO 8601) | Creation timestamp |
updated_at | string (ISO 8601) | Last update timestamp |