Llistar execucions d'automatització

Recorre l'historial d'execucions d'automatització de l'empresa autenticada amb paginació per cursor, filtrant per status, per automation_rule_id o per finestra de creació.

Pren el scope propi automation_runs:read en lloc del que llegeix regles, perquè una execució porta a dins el data.object congelat de l'esdeveniment que la va disparar —imports, destinataris, resultats de les accions— i això es concedeix a part.
Les pàgines s'ordenen per id ascendent, així que l'historial es llegeix del més antic al més recent; recorre'l amb ending_before per anar en sentit contrari.

Paràmetres de consulta

automation_rule_id?string

ID (UUID v7) de la regla d'automatització les execucions de la qual es llisten.

Formatuuid

subject_company_id?string

ID (UUID v7) de l'empresa gestionada sobre la qual va actuar l'execució. Només les empreses que gestiones donen resultats.

Formatuuid

limit?integer

Nombre d'objectes a retornar. Enter entre 1 i 100. Per defecte 25.

Predeterminat25

Rang1 <= value <= 100

starting_after?string

Cursor per a paginació cap endavant. Fes servir l'uuid de l'últim objecte de la pàgina anterior.

Formatuuid

ending_before?string

Cursor per a paginació cap enrere. Fes servir l'uuid del primer objecte de la pàgina actual.

Formatuuid

status?string

Estat de l'execució. dead_lettered i failed són els que val la pena rellançar; blocked significa que un límit del motor l'ha aturada abans d'executar. Coincidència exacta amb status.

created[gte]?string

Data de creació (ISO 8601). Major o igual que el valor donat.

Formatdate-time

created[lte]?string

Data de creació (ISO 8601). Menor o igual que el valor donat.

Formatdate-time

created[gt]?string

Data de creació (ISO 8601). Estrictament major que el valor donat.

Formatdate-time

created[lt]?string

Data de creació (ISO 8601). Estrictament menor que el valor donat.

Formatdate-time

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

X-Active-Profile?string

Opera en nom d'una empresa filla (API key mestra de gestoria): passa el seu id públic (UUID v7) i la petició s'executa contra les dades d'aquella filla sense canviar l'scope, el tier ni l'environment de la clau (omet-lo per usar la pròpia empresa de la clau). UUID no vàlid → 400 parameter_invalid_uuid; id desconegut o no propi → 404 profile_not_found. Consulta la guia d'Acting on behalf.

Formatuuid

Cos de la resposta

`application/json`

Exemple de petició

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());

Exemple de resposta

{
  "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 l'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"
  }
}

Format d'API key no vàlid

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

L'API key no té el scope requerit

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

Cal millorar el pla

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

Pla sense accés a l'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àmetre no ha superat la validació

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

Format d'Idempotency-Key no vàlid

{
  "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ímit de peticions superat

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

Massa errors d'autenticació (bloqueig 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"
  }
}

Llistar execucions d'automatització

Authorization

Paràmetres de consulta

Headers

Cos de la resposta

200application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`