WorkflowRun

Um WorkflowRun é uma execução da cadeia de requisições que o agente devolveu em workflow — veja Workflows do agente para saber como um agente produz uma.

É somente leitura pela API: uma execução existe porque um agente a produziu, e nada fora do runner de agentes consegue criar uma.

Para que serve

• Registrar o que foi chamado depois que um e-mail foi processado, e o que cada destino respondeu.
• Tornar uma falha diagnosticável sem reexecutar: a requisição e a resposta guardadas bastam para entender o que houve.
• Dar a quem assina webhooks um sinal terminal (workflow.run.succeeded / workflow.run.failed) para agir.

Ciclo de vida

pending ──▶ running ──▶ success
                   └──▶ failed

Os passos executam em sequência e todos são tentados: um passo que falha fica failed sozinho, um passo que referencia outro que não teve sucesso fica skipped (nunca é enviado), e a execução fica failed se algum passo falhou. Nada é repetido automaticamente — um passo é uma requisição arbitrária aos seus sistemas, e repeti-la poderia duplicar o que ela criou.

Schema

Campo	Tipo	Descrição
id	UUID	Id interno.
workspace_id	UUID	Workspace dono.
inbox_id / email_id / agent_id / agent_run_id	UUID | null	O que produziu a execução.
status	enum	pending, running, success, failed.
definition	array	O array workflow exatamente como o agente devolveu, com os placeholders não resolvidos.
summary.total	int	Quantidade de passos.
summary.succeeded	int	Quantos concluíram com sucesso.
summary.error	int	total - succeeded: passos failed mais passos skipped por dependerem de um que não teve sucesso. Uma execução pode ter vários de cada.
error	string | null	Preenchido quando a execução falhou: todos os passos que falharam, um por linha, cada um como step <posição>: <erro>.
duration_ms	int | null	Tempo total da cadeia.
started_at / finished_at	datetime | null
created_at / updated_at	datetime
steps	array	Só em GET /v1/workflow-runs/{id} — a listagem os omite.

Passo

Campo	Tipo	Descrição
id	UUID	Id interno.
position	int	Índice base 0 no workflow, que também é a ordem de execução.
type	enum	request (único tipo hoje).
status	enum	pending, running, success, failed, skipped.
request.method	string | null
request.url	string | null	A URL como enviada, com valores de secrets substituídos por [REDACTED].
request.headers	object | null	Mesma redação.
request.body	string | null	Mesma redação, truncado em 4000 caracteres. Um anexo do e-mail referenciado como base64 aparece como [attachment N: nome, content type, tamanho], nunca como os bytes.
request.form	object | null	Campos multipart de um passo com form, como enviados. Um campo de arquivo é um descritor { attachment, filename, content_type, size } do anexo do e-mail que foi enviado. null num passo com body.
response.status	int | null
response.headers	object | null
response.body	string | null	Truncado em 4000 caracteres.
response.expected_status	int | null	O status que conta como sucesso. null significa qualquer 2xx.
error	string | null	Por que o passo falhou.
duration_ms	int | null
started_at / finished_at	datetime | null

Endpoints

Método	Caminho	Observações
GET	/v1/workflow-runs	Lista. Paginação por keyset; filtre por status, email_id, inbox_id, agent_id, agent_run_id e intervalos de data.
GET	/v1/workflow-runs/{id}	Uma execução com todos os passos, na ordem de execução.

Escopo: inbox/workflow_runs.

Exemplo

{
  "id": "9c8b7a65-4321-4fed-9876-0123456789ab",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "email_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
  "agent_run_id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
  "status": "failed",
  "definition": [
    {
      "type": "request",
      "method": "POST",
      "url": "https://erp.example.com/payables",
      "headers": { "Authorization": "Bearer ${{secrets.FINANCE_TOKEN}}" },
      "expected_status": 201
    }
  ],
  "summary": { "total": 1, "succeeded": 0, "error": 1 },
  "error": "step 0: expected status 201, got 422",
  "duration_ms": 318,
  "steps": [
    {
      "position": 0,
      "type": "request",
      "status": "failed",
      "request": {
        "method": "POST",
        "url": "https://erp.example.com/payables",
        "headers": { "Authorization": "Bearer [REDACTED]" },
        "body": null,
        "form": null
      },
      "response": {
        "status": 422,
        "headers": null,
        "body": "{\"error\":\"supplier not found\"}",
        "expected_status": 201
      },
      "error": "expected status 201, got 422",
      "duration_ms": 318
    }
  ]
}