Obter Audiência

Obtenha um audience criteria por id, com sua definição completa — blocos de consulta e composições aninhadas.

GET /api/audience-criterias/:id

Retorna um único audience criteria com sua definição completa: os dados base do recurso mais a árvore aninhada de blocos de consulta (queryBlocks) e composições (compositions).

Auth: Obrigatória — permissão audience-criteria:view

Parâmetros de Rota

Parâmetro	Tipo	Descrição
`id`	UUID	O id do audience criteria.

Exemplo

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;

Resposta `200 OK`

A resposta é o recurso base mais queryBlocks (ordenado por order ascendente) e compositions. Todos os campos usam camelCase; os instantes são serializados em 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"
    }
  ]
}

Campos base

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador do critério.
`projectId`	string (UUID)	Projeto ao qual o critério pertence.
`name`	string	Nome do critério.
`description`	string \| null	Descrição; `null` se não houver.
`isActive`	boolean	Se o critério está ativo.
`isRoot`	boolean	`true` apenas para a audiência raiz do projeto (veja Projetos).
`ownerId`	string (UUID)	Usuário criador.
`updatedBy`	string (UUID)	Último usuário que o editou.
`createdAt`	string (ISO 8601)	Data de criação.
`updatedAt`	string (ISO 8601)	Data da última atualização.

Array de blocos de consulta, ordenado por order ascendente. Cada bloco descreve uma consulta (tabela, colunas, filtros, tempo, joins e agregações) que depois é combinada com as demais via setOperator.

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador do bloco.
`order`	number	Posição do bloco (ascendente).
`setOperator`	`SetOperatorEnum` \| null	Operador de conjunto que combina este bloco com o resultado anterior; `null` no primeiro bloco.
`from`	object	Fonte de dados: `{ table: string, joins: IJoin[], unnests: IColumnRef[] }` — tabela base, joins e fontes de linhas (`unnests` é sempre `[]` em uma audiência).
`select`	object	Seleção: `{ distinct: boolean, items: ISelectItem[] }` — colunas ou agregados.
`timeWindow`	object \| null	Janela temporal (união discriminada por `timeOperator`); `null` se não aplicável.
`where`	object	Árvore de filtros: grupos recursivos `AND`/`OR` com predicados de coluna.
`groupBy`	`IColumnRef[]` \| null	Colunas de agrupamento, ou `null`.
`having`	object \| null	Árvore de filtros sobre agregados (mesma forma que `where`, com folhas sobre um agregado), ou `null`.

Onde:

from — table é a tabela base do catálogo; cada elemento de joins é { type: JoinTypeEnum, table: string, on: IJoinPredicate[] }, e cada predicado de join é { left: IColumnRef, right: IColumnRef }. Um IColumnRef é { table: string, column: string }.
select.items — cada item é uma coluna ({ kind: "column", column: IColumnRef, alias?: string }) ou um agregado ({ kind: "aggregate", aggregate: IAggregate, alias: string }).
timeWindow — sua forma depende de timeOperator: ALL_TIME não leva mais campos; IN_THE_LAST / IN_THE_FIRST levam reference, unit e value; SINCE leva reference e from; BETWEEN leva reference, from e to.

A estrutura completa da árvore de filtros (where / having), da seleção e da janela temporal está documentada em detalhe em Criar e Gerar SQL. Os valores de cada enum estão no glossário da seção.

`compositions[]`

Array de composições: outras audiências combinadas com esta via um operador de conjunto.

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador da composição.
`operandCriteriaId`	string (UUID)	Id do audience criteria operando que está sendo combinado.
`operandCriteriaName`	string	Nome do critério operando (`''` se não puder ser resolvido).
`setOperator`	`SetOperatorEnum`	Operador de conjunto que combina a audiência operando.

Respostas de Erro

Status	Descrição
`401`	Ausente ou inválido o `Authorization: Bearer`.
`403`	O usuário não tem a permissão `audience-criteria:view`, ou o `x-tenant-id` não está autorizado.
`404`	Não existe um audience criteria com esse `id` no projeto ativo.