Get Audience

Get an audience criteria by id, with its full definition — nested query blocks and compositions.

GET /api/audience-criterias/:id

Returns a single audience criteria with its full definition: the resource's base data plus the nested tree of query blocks (queryBlocks) and compositions (compositions).

Auth: Required — audience-criteria:view permission

Path Parameters

Parameter	Type	Description
`id`	UUID	The audience criteria id.

Example

curl https://api.reten.ai/api/audience-criterias/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>"

import axios from 'axios';

const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await axios.get(
  `https://api.reten.ai/api/audience-criterias/${id}`,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const criteria = response.data;

Response `200 OK`

The response is the base resource plus queryBlocks (ordered by order ascending) and compositions. All fields use camelCase; instants are serialized to ISO 8601.

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "name": "Clientes activos últimos 30 días",
  "description": "Usuarios con al menos una compra pagada en el último mes",
  "isActive": true,
  "isRoot": false,
  "ownerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "updatedBy": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "createdAt": "2026-06-10T14:00:00.000Z",
  "updatedAt": "2026-06-15T09:30:00.000Z",
  "queryBlocks": [
    {
      "id": "2a8f0c11-6b22-4d33-8e44-aa55bb66cc77",
      "order": 0,
      "setOperator": null,
      "from": {
        "table": "event_transactions",
        "joins": [
          {
            "type": "INNER",
            "table": "user_properties",
            "on": [
              {
                "left": { "table": "event_transactions", "column": "user_id" },
                "right": { "table": "user_properties", "column": "user_id" }
              }
            ]
          }
        ],
        "unnests": []
      },
      "select": {
        "distinct": true,
        "items": [
          {
            "kind": "column",
            "column": { "table": "event_transactions", "column": "user_id" },
            "alias": "user_id"
          }
        ]
      },
      "timeWindow": {
        "timeOperator": "IN_THE_LAST",
        "reference": { "table": "event_transactions", "column": "event_date" },
        "unit": "DAYS",
        "value": 30
      },
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "event_transactions", "column": "status" },
            "comparisonOperator": "EQUALS",
            "value": "COMPLETED"
          }
        ]
      },
      "groupBy": null,
      "having": null
    },
    {
      "id": "5d1c3f44-9e55-4066-b177-dd88ee99ffaa",
      "order": 1,
      "setOperator": "UNION_DISTINCT",
      "from": { "table": "user_segment_relation", "joins": [], "unnests": [] },
      "select": {
        "distinct": true,
        "items": [
          {
            "kind": "column",
            "column": { "table": "user_segment_relation", "column": "user_id" },
            "alias": "user_id"
          }
        ]
      },
      "timeWindow": { "timeOperator": "ALL_TIME" },
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "user_segment_relation", "column": "segment_id" },
            "comparisonOperator": "IN",
            "value": ["high-value", "vip"]
          }
        ]
      },
      "groupBy": null,
      "having": null
    }
  ],
  "compositions": [
    {
      "id": "8a4f6277-c188-4399-e400-aa00bb11ccdd",
      "operandCriteriaId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "operandCriteriaName": "Clientes VIP",
      "setOperator": "INTERSECT_DISTINCT"
    }
  ]
}

Base Fields

Field	Type	Description
`id`	string (UUID)	Criteria identifier.
`projectId`	string (UUID)	Project the criteria belongs to.
`name`	string	Criteria name.
`description`	string \| null	Description; `null` if none.
`isActive`	boolean	Whether the criteria is active.
`isRoot`	boolean	`true` only for the project's root audience (see Projects).
`ownerId`	string (UUID)	Creating user.
`updatedBy`	string (UUID)	Last user who edited it.
`createdAt`	string (ISO 8601)	Creation date.
`updatedAt`	string (ISO 8601)	Last update date.

`queryBlocks[]`

Array of query blocks, ordered by order ascending. Each block describes a query (table, columns, filters, time, joins, and aggregations) that is then combined with the others via setOperator.

Field	Type	Description
`id`	string (UUID)	Block identifier.
`order`	number	Block position (ascending).
`setOperator`	`SetOperatorEnum` \| null	Set operator that combines this block with the previous result; `null` on the first block.
`from`	object	Data source: `{ table: string, joins: IJoin[], unnests: IColumnRef[] }` — base table, joins and row sources (`unnests` is always `[]` in an audience).
`select`	object	Selection: `{ distinct: boolean, items: ISelectItem[] }` — columns or aggregates.
`timeWindow`	object \| null	Time window (union discriminated by `timeOperator`); `null` if not applicable.
`where`	object	Filter tree: recursive `AND`/`OR` groups with column predicates.
`groupBy`	`IColumnRef[]` \| null	Grouping columns, or `null`.
`having`	object \| null	Filter tree over aggregates (same shape as `where`, with leaves over an aggregate), or `null`.

Where:

from — table is the base table from the catalog; each joins element is { type: JoinTypeEnum, table: string, on: IJoinPredicate[] }, and each join predicate is { left: IColumnRef, right: IColumnRef }. An IColumnRef is { table: string, column: string }.
select.items — each item is a column ({ kind: "column", column: IColumnRef, alias?: string }) or an aggregate ({ kind: "aggregate", aggregate: IAggregate, alias: string }).
timeWindow — its shape depends on timeOperator: ALL_TIME carries no more fields; IN_THE_LAST / IN_THE_FIRST carry reference, unit, and value; SINCE carries reference and from; BETWEEN carries reference, from, and to.

The full structure of the filter tree (where / having), the selection, and the time window is documented in detail in Create and Generate SQL. The values of each enum are in the section glossary.

`compositions[]`

Array of compositions: other audiences combined with this one via a set operator.

Field	Type	Description
`id`	string (UUID)	Composition identifier.
`operandCriteriaId`	string (UUID)	Id of the operand audience criteria being combined.
`operandCriteriaName`	string	Operand criteria name (`''` if it cannot be resolved).
`setOperator`	`SetOperatorEnum`	Set operator that combines the operand audience.

Error Responses

Status	Description
`401`	Missing or invalid `Authorization: Bearer`.
`403`	The user lacks the `audience-criteria:view` permission, or the `x-tenant-id` is not authorized.
`404`	No audience criteria with that `id` exists in the active project.