Event Filters

Overview

An event filter (event criteria) is a set of events selected with a query-builder —table → columns → filters → time window → aggregations— without writing SQL by hand.

The definition is assembled by composing:

The full tree —with the three where leaves and all their fields— is documented once in Definition; the endpoint pages reference it instead of repeating it.

No identity column

An event filter projects events, not subjects: there is no mandatory identity column and the generated SQL returns subjectColumn: null. That is the structural difference with audiences, which do have to expose their identity in at least one block.

Endpoints

Base URL and environments

All routes hang off the global prefix /api under the /event-criterias resource (for example POST /api/event-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

Validation, authorization and resolution errors follow the API's standard error 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 is documented in List.

Enum glossary

Quick reference catalog. The field where each one appears and its exact shape are in Definition.

SetOperatorEnum

Combination of query blocks within the same filter (a block's setOperator).

• UNION_DISTINCT · UNION_ALL · INTERSECT_DISTINCT

LogicalOperatorEnum

Chaining of predicates within a group of the filter tree.

• AND · OR

ComparisonOperatorEnum

Operator of a predicate over a column or over a sub-field.

• 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 a scalar column of the events catalog. It determines which comparison operators it accepts.

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

Differences from audiences

Both resources share the query-builder, but they are not symmetric. If you arrive from audiences, these are the assumptions that do not carry over: