Listar ejecuciones de automatización

Recorre el historial de ejecuciones de automatización de la empresa autenticada con paginación por cursor, filtrando por status, por automation_rule_id o por ventana de creación.

Toma el scope propio automation_runs:read en lugar del que lee reglas, porque una ejecución lleva dentro el data.object congelado del evento que la disparó —importes, destinatarios, resultados de las acciones— y eso se concede aparte.
Las páginas se ordenan por id ascendente, así que el historial se lee de lo más antiguo a lo más reciente; recórrelo con ending_before para ir en sentido contrario.

Parámetros de consulta

automation_rule_id?string

ID (UUID v7) de la regla de automatización cuyas ejecuciones se listan.

Formatouuid

subject_company_id?string

ID (UUID v7) de la empresa gestionada sobre la que actuó la ejecución. Solo las empresas que gestionas dan resultados.

Formatouuid

limit?integer

Número de objetos a devolver. Entero entre 1 y 100. Por defecto 25.

Predeterminado25

Rango1 <= value <= 100

starting_after?string

Cursor para paginación hacia delante. Usa el uuid del último objeto de la página anterior.

Formatouuid

ending_before?string

Cursor para paginación hacia atrás. Usa el uuid del primer objeto de la página actual.

Formatouuid

status?string

Estado de la ejecución. dead_lettered y failed son los que vale la pena relanzar; blocked significa que un límite del motor la detuvo antes de ejecutar. Coincidencia exacta con status.

created[gte]?string

Fecha de creación (ISO 8601). Mayor o igual que el valor dado.

Formatodate-time

created[lte]?string

Fecha de creación (ISO 8601). Menor o igual que el valor dado.

Formatodate-time

created[gt]?string

Fecha de creación (ISO 8601). Estrictamente mayor que el valor dado.

Formatodate-time

created[lt]?string

Fecha de creación (ISO 8601). Estrictamente menor que el valor dado.

Formatodate-time

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

X-Active-Profile?string

Opera en nombre de una empresa hija (API key maestra de gestoría): pasa su id público (UUID v7) y la petición se ejecuta contra los datos de esa hija sin cambiar el scope, el tier ni el environment de la clave (omítelo para usar la propia empresa de la clave). UUID inválido → 400 parameter_invalid_uuid; id desconocido o no propio → 404 profile_not_found. Consulta la guía de Acting on behalf.

Formatouuid

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/automations/runs?limit=25", {  method: "GET",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json"} },});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63",
      "object": "automation_run",
      "automation_rule_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61",
      "rule_version": 2,
      "rule_snapshot": {
        "name": "Avisar de un cobro grande",
        "trigger_type": "invoice.paid",
        "scope": "empresa",
        "conditions": {
          "field": "total",
          "operator": "gte",
          "value": 1000
        },
        "actions": [
          {
            "type": "notify_in_app",
            "order": 0,
            "parameters": {
              "recipient_type": "role",
              "role": "admin",
              "category": "invoice",
              "title": "Cobro grande",
              "message": "Se ha cobrado una factura de 1000 EUR o más."
            }
          }
        ]
      },
      "trigger_type": "invoice.paid",
      "subject_company": {
        "id": null,
        "name": null
      },
      "event_name": "invoice.paid",
      "event_aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20",
      "event_occurred_on": "2026-03-16T11:05:00Z",
      "event_payload": {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20",
        "object": "invoice",
        "number": "FAC-2026-00042",
        "status": "paid",
        "total": "1250.00"
      },
      "correlation_id": "req_01HKQS5N7UR6PWJ8K2T5BWPMZ9",
      "chain_depth": 0,
      "status": "completed",
      "attempts": 1,
      "discard_reason": null,
      "discard_reason_label": null,
      "last_error": null,
      "started_at": "2026-03-16T11:05:01Z",
      "finished_at": "2026-03-16T11:05:02Z",
      "created_at": "2026-03-16T11:05:00Z",
      "updated_at": "2026-03-16T11:05:02Z",
      "steps": [
        {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64",
          "object": "automation_step_run",
          "step_index": 0,
          "action_type": "notify_in_app",
          "status": "succeeded",
          "attempts": 1,
          "parameters": {
            "recipient_type": "role",
            "role": "admin",
            "category": "invoice",
            "title": "Cobro grande",
            "message": "Se ha cobrado una factura de 1000 EUR o más."
          },
          "result": {
            "recipient_type": "role",
            "recipient": "admin",
            "category": "invoice",
            "title": "Cobro grande",
            "priority": "normal"
          },
          "discard_reason": null,
          "discard_reason_label": null,
          "replayable": false,
          "last_error": null,
          "next_retry_at": null,
          "claimed_at": "2026-03-16T11:05:01Z",
          "finished_at": "2026-03-16T11:05:02Z"
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}

Falta la API key

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

Formato de API key no válido

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key",
    "request_id": "req_01HKQS5N9JTQM7HVTQP3FBN5XB"
  }
}

API key revocada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada y ya no es válida.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01HKQS5NA8K7E2V9YDZWMT6RJC"
  }
}

La API key carece del scope requerido

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

Se requiere mejorar el plan

{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available_in_plan",
    "message": "Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#feature_not_available_in_plan",
    "request_id": "req_01HKQS5NCK4V9N2L7Y8X3WPMRE"
  }
}

Plan sin acceso a la API pública

{
  "error": {
    "type": "authorization_error",
    "code": "addon_not_active",
    "message": "Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#addon_not_active",
    "request_id": "req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"
  }
}

El parámetro no superó la validación

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

Formato de Idempotency-Key no válido

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_format",
    "message": "La Idempotency-Key debe tener entre 1 y 64 caracteres ASCII printable.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_format",
    "request_id": "req_01HKQS5NIDEMPKEYFORMAT0007"
  }
}

Límite de peticiones superado

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

Demasiados fallos de autenticación (bloqueo temporal)

{
  "error": {
    "type": "authentication_error",
    "code": "too_many_auth_failures",
    "message": "Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#too_many_auth_failures",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVM"
  }
}

Too many concurrent uploads in flight

{
  "error": {
    "type": "rate_limit_error",
    "code": "upload_in_flight_budget_exceeded",
    "message": "Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded",
    "request_id": "req_01HKQS5NUPLOADINFLIGHT005"
  }
}

Company-wide rate limit exceeded (all keys combined)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_rate_limit_exceeded",
    "message": "Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded",
    "request_id": "req_01HKQS5NCOMPANYRATELIMIT06"
  }
}

Company-wide monthly quota exhausted (all keys combined)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_monthly_quota_exceeded",
    "message": "Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NCOMPANYMONTHLY0007"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Listar ejecuciones de automatización

Authorization

Parámetros de consulta

Headers

Cuerpo de la respuesta

200application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`