WorkflowRun

Un WorkflowRun es una ejecución de la cadena de peticiones que el agente devolvió en workflow — vea Workflows del agente para saber cómo un agente produce una.

Es de solo lectura por la API: una ejecución existe porque un agente la produjo, y nada fuera del runner de agentes puede crear una.

Para qué sirve

• Registrar qué se llamó después de procesar un correo, y qué respondió cada destino.
• Hacer diagnosticable un fallo sin reejecutar: la petición y la respuesta guardadas bastan para ver qué pasó.
• Dar a quien se suscribe a webhooks una señal terminal (workflow.run.succeeded / workflow.run.failed) sobre la que actuar.

Ciclo de vida

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

Los pasos se ejecutan en secuencia y todos se intentan: un paso que falla queda failed por sí solo, un paso que referencia a otro que no tuvo éxito queda skipped (nunca se envía), y la ejecución queda failed si algún paso falló. Nada se reintenta automáticamente — un paso es una petición arbitraria a sus sistemas, y repetirla podría duplicar lo que creó.

Schema

Campo	Tipo	Descripción
id	UUID	Id interno.
workspace_id	UUID	Workspace propietario.
inbox_id / email_id / agent_id / agent_run_id	UUID | null	Lo que produjo la ejecución.
status	enum	pending, running, success, failed.
definition	array	El array workflow exactamente como lo devolvió el agente, con los placeholders sin resolver.
summary.total	int	Cantidad de pasos.
summary.succeeded	int	Cuántos terminaron con éxito.
summary.error	int	total - succeeded: pasos failed más pasos skipped por depender de uno que no tuvo éxito. Una ejecución puede tener varios de cada uno.
error	string | null	Se completa cuando la ejecución falló: todos los pasos que fallaron, uno por línea, cada uno como step <posición>: <error>.
duration_ms	int | null	Tiempo total de la cadena.
started_at / finished_at	datetime | null
created_at / updated_at	datetime
steps	array	Solo en GET /v1/workflow-runs/{id} — el listado los omite.

Paso

Campo	Tipo	Descripción
id	UUID	Id interno.
position	int	Índice base 0 en el workflow, que también es el orden de ejecución.
type	enum	request (único tipo por ahora).
status	enum	pending, running, success, failed, skipped.
request.method	string | null
request.url	string | null	La URL tal como se envió, con los valores de secrets reemplazados por [REDACTED].
request.headers	object | null	Misma redacción.
request.body	string | null	Misma redacción, truncado a 4000 caracteres. Un adjunto del correo referenciado como base64 se muestra como [attachment N: nombre, content type, tamaño], nunca como sus bytes.
request.form	object | null	Campos multipart de un paso con form, tal como se enviaron. Un campo de archivo es un descriptor { attachment, filename, content_type, size } del adjunto del correo que se subió. null en un paso con body.
response.status	int | null
response.headers	object | null
response.body	string | null	Truncado a 4000 caracteres.
response.expected_status	int | null	El status que cuenta como éxito. null significa cualquier 2xx.
error	string | null	Por qué falló el paso.
duration_ms	int | null
started_at / finished_at	datetime | null

Endpoints

Método	Ruta	Notas
GET	/v1/workflow-runs	Lista. Paginación por keyset; filtre por status, email_id, inbox_id, agent_id, agent_run_id y rangos de fecha.
GET	/v1/workflow-runs/{id}	Una ejecución con todos sus pasos, en orden de ejecución.

Scope: inbox/workflow_runs.

Ejemplo

{
  "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
    }
  ]
}