GET/api/v1/tasks

Listar tasks

Bearer tokenImplementadoescopo read:tasks

Contrato OpenAPI

operationId: listTasks · Implementada

Parâmetros

Nome	Local	Obrigatório	Tipo
`limit`	query	não	integer
`offset`	query	não	integer
`status`	query	não	string

Respostas

HTTP	Significado
`200`	Página de tasks do usuário
`default`	Erro padronizado

Lista as tasks de geração do usuário associado ao Bearer token. Suporta filtro por status e paginação. Responde 200 OK.

Escopo necessário: read:tasks (ver Escopos).

O caso de uso de "minhas gerações concluídas" equivale a GET /api/v1/tasks?status=completed. O resultUrl de cada task é obtido em GET /api/v1/tasks/:id.

Query params

Param	Tipo	Padrão	Restrições
`status`	string	—	filtra pelo status da task. Valores aceitos: `pending`, `submitted`, `processing`, `completed`, `failed`
`limit`	inteiro	`20`	máximo `100`
`offset`	inteiro	`0`	deslocamento para paginação (máximo `10000`)

Ver Paginação.

Exemplo de request

cURL

curl "https://avatrix.io/api/v1/tasks?status=completed&limit=20&offset=0" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx"

Resposta — 200

A lista vem dentro do envelope padrão:

JSON

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "tsk_xxxxxxxx",
        "toolId": "image-generator",
        "status": "completed",
        "progress": 100,
        "createdAt": "2026-06-16T12:00:00.000Z",
        "updatedAt": "2026-06-16T12:01:30.000Z"
      }
    ],
    "limit": 20,
    "offset": 0
  }
}

As tasks vêm ordenadas da mais recente para a mais antiga. Os status de cada task seguem o Ciclo de vida da task: pending → submitted → processing → completed | failed. Para o resultUrl e demais detalhes use GET /api/v1/tasks/:id.

Erros relevantes

Código	HTTP	Quando
`UNAUTHORIZED`	401	token ausente, inválido, expirado ou revogado
`FORBIDDEN`	403	token sem `read:tasks`
`VALIDATION_ERROR`	400	parâmetro `status` com valor inválido
`RATE_LIMITED`	429	rate limit (60 req/min por token), com `Retry-After`

Ver Erros.