---
title: "List your automation rules"
method: GET
path: "/companies/{company}/automations/rules"
tags: ["Automations"]
---

# List your automation rules

`GET /companies/{company}/automations/rules`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/automations/rules`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

List the company’s automation rules with cursor-based pagination, ordered by `id` ascending.
- Filter by `status`, `trigger_type`, creation window (`created[gte]`, `created[lte]`) and search by name with `search`.
- A cursor issued for another company yields an empty page.

## Path parameters

- `company` string, uuid, required

## Query parameters

- `limit` integer
- `starting_after` string, uuid
- `ending_before` string, uuid
- `status` 'draft' | 'active' | 'paused'
- `trigger_type` string
- `scope` 'empresa' | 'cartera'
- `created[gte]` string, date-time
- `created[lte]` string, date-time
- `created[gt]` string, date-time
- `created[lt]` string, date-time
- `search` string

## Headers

- `Factuarea-Version` string, date

## Response `200`

- object: Cursor-paginated list envelope shared by every v1 listing endpoint. `data` holds the page items; `has_more` signals whether another page exists; `next_cursor` is the cursor to pass back for the following page. Treat it as strictly opaque: send it through verbatim, never parse it and never assume a format — it is not the same across listings, and each listing documents its own cursor parameter. Concrete listings narrow `data` to their resource type via `allOf`.
  - `data` object[], required: Items on the current page.
    - `id` string, uuid, required: Opaque identifier of the automation rule, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).
    - `object` 'automation_rule', required: Always `automation_rule`.
    - `name` string, required: Name the account owner gave the automation.
    - `description` string, nullable, required: Free-form description of what the automation is for, or `null`.
    - `trigger_type` string, required: Event the automation listens to, in `resource.action` form (e.g. `invoice.paid`). It is one of the event types returned by `GET /v1/event-catalog`.
    - `scope` 'empresa' | 'cartera', required: Which tax IDs the automation watches: `empresa` (the default, and the scope of every rule created before portfolio automations existed) watches only the events of the company that owns it, while `cartera` is reserved for the titular company of an account with the gestoría module and watches the events of the other tax IDs the account operates (its own and those another account lets it operate), delivering the notices to the titular itself. It is fixed when the rule is created and cannot be changed afterwards, so a run stays attributable to the scope it executed under.
    - `conditions` object, required: Condition tree of the current version that decides whether an incoming event triggers the actions. An empty object `{}` means the automation has no condition and always acts. Its shape is defined by the account owner (nested combinators over the fields of the trigger payload), so it is returned verbatim.
    - `actions` object[], required: Actions of the current version, in the order the account owner declared them. Each element carries its action type and its frozen parameters. An empty array means the version declares no action.
    - `status` 'draft' | 'active' | 'paused', required: State of the automation: `draft` (not listening yet), `active` (listening) or `paused` (not listening; either paused by a person or auto-paused by the platform after a streak of failures).
    - `current_version` integer, required: Number of the current version of the definition. Editing an automation creates a new version instead of mutating the previous one, so every run keeps a pointer to the exact definition it executed.
    - `created_at` string, date-time, nullable, required: When the automation was created (ISO 8601).
    - `updated_at` string, date-time, nullable, required: When the automation was last modified (ISO 8601).
  - `has_more` boolean, required: Whether more pages are available after this one.
  - `next_cursor` string, nullable, required: Opaque cursor for the next page, or `null` when `has_more` is `false`. The example below shows the shape used by most listings; others return a different one, so pass the value back verbatim instead of validating it.

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). `company_inactive`: the company in the path is deactivated; reactivate it to operate.
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)