Paginação, ordenação e filtros

Cursor

As listagens são paginadas por cursor:

Parâmetro	Padrão	Regra
limit	25	de 1 a 100
cursor	—	o meta.next_cursor da página anterior

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  "https://api.kadu.ia.br/v1/executions?limit=50"

{
  "data": [ … ],
  "meta": { "next_cursor": "eyJpZCI6IjJmMWMi…", "limit": 50 }
}

Repita a chamada com cursor=<next_cursor> até next_cursor vir null. O cursor é opaco: não o monte nem o interprete. Um cursor inválido responde 400 VALIDATION_ERROR.

Ordenação

Parâmetro	Padrão	Valores
sort_by	created_at	created_at, updated_at ou um campo filtrável do recurso
sort_order	desc	asc ou desc

Filtros

Cada recurso aceita filtros em campos específicos, na forma campo=valor ou campo[operador]=valor:

Operador	Exemplo	Significado
(nenhum)	status=failed	igual
in	status[in]=failed,cancelled	um dos valores, separados por vírgula
gte, lte, gt, lt	reference_date[gte]=2026-10-01	maior ou igual, menor ou igual, maior, menor
not	status[not]=success	diferente

Exemplos de campos filtráveis:

Recurso	Campos
/v1/tasks	workspace_id, activity_id, skill_slug (igual ou in)
/v1/executions	task_id, workspace_id, activity_id, status (igual ou in); reference_date, started_at (gte, lte)

Um operador que o campo não aceita responde 400 VALIDATION_ERROR. Um parâmetro que não é filtro do recurso é ignorado.

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  "https://api.kadu.ia.br/v1/executions?status[in]=failed,cancelled&reference_date[gte]=2026-10-01&sort_order=asc"

Listas sem cursor

Algumas listagens devolvem um conjunto fixo, sem paginação: as entregas de webhook (as 50 mais recentes), os membros da organização (até 100) e os eventos de sistema (os 100 mais recentes). A referência de cada endpoint diz qual é o caso.