Audiences

Overview

An Audience Criteria is a segment of users or commerces defined with a query-builder —table → columns → filters → joins → aggregations → combination of blocks and audiences— without writing SQL by hand.

The definition is assembled by composing:

Identity column

Every audience criteria is a segment with its own identity: at least one of its query blocks must project the base table's identity column (for example user_id). That rule is unconditional — a definition that does not expose it is rejected with 400.

Endpoints

Base URL and environments

All routes hang off the global prefix /api under the /audience-criterias resource (for example POST /api/audience-criterias).

Authentication

All endpoints require a JWT Bearer token, the x-tenant-id header that identifies the tenant on whose schema the request operates, and the x-project-id header that identifies the project the request works in (see Authentication → Project Context).

-H "Authorization: Bearer <access_token>"
-H "x-tenant-id: <tenant-id>"
-H "x-project-id: <project-id>"

Permissions

Each route requires a specific permission:

Status codes

Error format

Errors follow the API's standard format:

{
  "statusCode": 400,
  "message": ["name should not be empty"],
  "error": "Bad Request"
}

On DTO validation errors, message is an array of strings (one entry per broken rule). Validation is strict: undeclared properties are rejected, so sending an unknown field produces a 400.

Pagination

The list wraps results in PaginatedResponseDto<T>:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "total_pages": 0,
    "has_next": false,
    "has_previous": false
  }
}

The detail of the pagination parameters (page, per_page, filters) is documented in List.

Enum glossary

Quick reference catalog. Each endpoint page re-lists the valid values next to the field where they appear.

SetOperatorEnum

Combination of blocks/audiences in composedWith.

• UNION_DISTINCT · UNION_ALL · INTERSECT_DISTINCT

LogicalOperatorEnum

Chaining of predicates within a group.

• AND · OR

ComparisonOperatorEnum

Operator of a predicate over a column.

• EQUALS · NOT_EQUALS · GREATER_THAN · LESS_THAN · GREATER_THAN_OR_EQUAL · LESS_THAN_OR_EQUAL · CONTAINS · NOT_CONTAINS · STARTS_WITH · ENDS_WITH · IS_NULL · IS_NOT_NULL · IN · NOT_IN · BETWEEN

AggregationOperatorEnum

Aggregation function over an operand (a column, * or an arithmetic expression).

• COUNT · SUM · AVG · MIN · MAX

ArithmeticOperatorEnum

Operator of an arithmetic expression inside an aggregate's operand. SAFE_DIVIDE yields NULL when the denominator is zero.

• ADD · SUBTRACT · MULTIPLY · SAFE_DIVIDE

TimeOperatorEnum

Operator of the time window (timeWindow).

• ALL_TIME · IN_THE_LAST · IN_THE_FIRST · SINCE · BETWEEN

TimeUnitEnum

Unit of the time window.

• DAYS · WEEKS · MONTHS · YEARS

JoinTypeEnum

Type of join between catalog tables.

• INNER · LEFT · RIGHT · FULL

CatalogFieldTypeEnum

Data type of an audiences catalog field.

• STRING · TIMESTAMP · BOOLEAN · FLOAT64 · INT64 · NUMERIC · BIGNUMERIC

Value shape by comparison operator

The shape that value takes depends on the predicate's comparisonOperator: