# List rules

List workspace automations and your own personal automations, with the status of their latest runs. Execution definitions stay in Brigg; this view contains no SQL, action payloads or generated run contents.

POST https://api.brigg.app/v1/operations/automation.ListRules

## Access & visibility

Allow `automation.ListRules` on your API key.

**Acting member required.** Send `Brigg-Act-As` with an [approved member account ID](https://developer.brigg.app/authentication#member-delegation). The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

[Set up authentication](https://developer.brigg.app/authentication) · [Choose permissions](https://developer.brigg.app/permissions)

## Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `app_id` | string | No | Use the owning app's app_id from ListApps, or core for workspace-native automations. This is not a public operation namespace. Omit only when the request field is optional. [workspace.ListApps](https://developer.brigg.app/reference/workspace/ListApps). |
| `limit` | integer | No | Maximum number of visible rules to return, newest-created first. Defaults to 50; this operation has no continuation cursor. Use app_id to narrow the catalogue. Maximum: 50. Greater than 0. |

## Inspect before changing an automation

Find a rule with [List rules](https://developer.brigg.app/reference/automation/ListRules), then read [Get rule](https://developer.brigg.app/reference/automation/GetRule) for its current configuration and recent runs. Preserve the `rule_id` and `app_id` pair. `enabled` controls future trigger handling; it is not a report that an earlier run succeeded.

Check `can_manage` before offering an edit or delete action. Built-in locked rules may be visible without being editable. The public update can pause a rule with enabled: false. It cannot resume a rule or author new actions; perform those steps in Brigg.

## Response

Returns **200 OK** with a JSON body.

This operation has no continuation cursor. An empty `items` array means no matching visible results were returned.

This is a bounded operational view, not a full export or change feed. If the result reaches limit, additional matching rules may exist. Use an app filter for a narrower view; do not invent a cursor or offset.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of [Automation rule](#automation-rule-response-items) | Yes | Rules visible to the acting member, optionally restricted to app_id and bounded by limit. This operation has no cursor pagination. |

### Automation rule · response.items[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rule_id` | string | Yes | Rule ID returned by the rule catalogue; use it with GetRule or UpdateRule. |
| `app_id` | string | Yes | App that owns the rule. This is an app ID, not a public operation namespace. |
| `description` | string or null | No | Descriptive text. |
| `trigger` | [object](#response-items-trigger) | No | Event or schedule that starts this rule; the fields depend on type. |
| `enabled` | boolean | Yes | Whether new matching events can start this rule. It does not report the outcome of past runs. |
| `locked` | boolean | Yes | Built-in: neither disabled nor deleted. |
| `scope` | string | Yes | `org` for an org-level rule, `mine` for the caller's own. |
| `can_manage` | boolean | Yes | Whether the acting member can manage this rule. Locked built-in rules cannot be disabled or deleted. |
| `created_at` | number | Yes | Creation time in Unix milliseconds. |
| `last_run` | [object](#response-items-last-run) or null | Yes | Most recent execution summary, or null if the rule has never run. |

### response.items[].trigger

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | Type identifying which variant of this model applies. Allowed: `"on_cron"`, `"on_create"`, `"on_update"`, `"on_delete"`, `"on_message"`. |
| `schedule` | string | No | Cron expression for an on_cron trigger, typically minute hour day-of-month month day-of-week. For example, 0 9 * * 1-5 runs at 09:00 on weekdays in timezone. Not present on record-change triggers. |
| `timezone` | string | No | IANA time zone, for example Europe/Oslo. |
| `resource_type` | string | No | Resource type whose changes can trigger this automation. |
| `fields` | array of string | No | Record fields whose changes the trigger observes. |
| `transition` | [object](#response-items-trigger-transition) | No | Field-value transition that qualifies a record change. |
| `channel` | string | No | Communication channel to which this trigger applies. |

### response.items[].trigger.transition

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | Yes | Record field whose change the trigger observes. |
| `to` | string or boolean or number | Yes | Destination value that the field must change to. |

### response.items[].last_run

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `run_id` | string | No | Run identifier. |
| `rule_id` | string | No | Rule identifier. |
| `app_id` | string | No | App identifier. |
| `trigger_type` | string | No | Trigger category identifying how the automation starts. |
| `status` | string | No | `ok` / `partial` / `error` / `skipped` — the roll-up over the rule's actions. |
| `fired_at` | number | No | Time of this trigger activation, in Unix milliseconds. |

## Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See [HTTP errors](https://developer.brigg.app/http#errors) and [safe retries and limits](https://developer.brigg.app/reliability).

| HTTP status | Code | What to do |
| --- | --- | --- |
| 400 | `invalid_json` | Send a JSON object with Content-Type: application/json. |
| 400 | `invalid_input` | Check the request fields and types. |
| 401 | `invalid_key` | The workspace API key is missing, invalid or revoked. |
| 403 | `forbidden` | Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply. |
| 404 | `not_found` | The requested operation or resource is not available to this credential. |
| 429 | `rate_limited` | Wait for Retry-After before retrying. |

## Next steps

- [Get rule](https://developer.brigg.app/reference/automation/GetRule)
- [Update rule](https://developer.brigg.app/reference/automation/UpdateRule)
- [List apps](https://developer.brigg.app/reference/workspace/ListApps)

[Download OpenAPI](https://developer.brigg.app/openapi.json) · [Versioning & retirement](https://developer.brigg.app/versioning)

## Examples

### Recent rule outcomes

A failed last run does not disable a rule automatically. Read GetRule with this rule_id/app_id pair for recent execution summaries.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/automation.ListRules' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "app_id": "core",
  "limit": 20
}'
```

#### TypeScript


```typescript
const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/automation.ListRules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "app_id": "core",
    "limit": 20
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);
```

#### Python


```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "app_id": "core",
  "limit": 20
}
request = Request(
    "https://api.brigg.app/v1/operations/automation.ListRules",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise
```

#### Response example


```json
{
  "items": [
    {
      "rule_id": "rule_follow_up",
      "app_id": "core",
      "description": "Create a follow-up task when a deal changes stage.",
      "trigger": {
        "type": "on_update",
        "resource_type": "core:Deal",
        "fields": [
          "stage"
        ]
      },
      "enabled": true,
      "locked": false,
      "scope": "org",
      "can_manage": true,
      "created_at": 1794301200000,
      "last_run": {
        "run_id": "run_follow_up_1",
        "rule_id": "rule_follow_up",
        "app_id": "core",
        "trigger_type": "on_update",
        "status": "error",
        "fired_at": 1794387600000
      }
    }
  ]
}
```

## JSON schemas


```json-schema-request
{
  "type": "object",
  "properties": {
    "app_id": {
      "type": "string",
      "description": "Use the owning app's app_id from ListApps, or core for workspace-native automations. This is not a public operation namespace. Omit only when the request field is optional. [workspace.ListApps](https://developer.brigg.app/reference/workspace/ListApps)."
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 50,
      "description": "Maximum number of visible rules to return, newest-created first. Defaults to 50; this operation has no continuation cursor. Use app_id to narrow the catalogue."
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "app_id": "core",
      "limit": 20
    }
  ]
}
```


```json-schema-response
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rule_id": {
            "type": "string",
            "description": "Rule ID returned by the rule catalogue; use it with GetRule or UpdateRule.",
            "examples": [
              "rule_follow_up"
            ]
          },
          "app_id": {
            "type": "string",
            "description": "App that owns the rule. This is an app ID, not a public operation namespace.",
            "examples": [
              "core"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Descriptive text.",
            "examples": [
              "Create a follow-up task when a deal changes stage."
            ]
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "on_cron",
                  "on_create",
                  "on_update",
                  "on_delete",
                  "on_message"
                ],
                "description": "Type identifying which variant of this model applies."
              },
              "schedule": {
                "type": "string",
                "description": "Cron expression for an on_cron trigger, typically minute hour day-of-month month day-of-week. For example, 0 9 * * 1-5 runs at 09:00 on weekdays in timezone. Not present on record-change triggers."
              },
              "timezone": {
                "type": "string",
                "description": "IANA time zone, for example Europe/Oslo."
              },
              "resource_type": {
                "type": "string",
                "description": "Resource type whose changes can trigger this automation."
              },
              "fields": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Record fields whose changes the trigger observes."
              },
              "transition": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "description": "Record field whose change the trigger observes."
                  },
                  "to": {
                    "type": [
                      "string",
                      "boolean",
                      "number"
                    ],
                    "description": "Destination value that the field must change to."
                  }
                },
                "required": [
                  "field",
                  "to"
                ],
                "additionalProperties": false,
                "description": "Field-value transition that qualifies a record change."
              },
              "channel": {
                "type": "string",
                "description": "Communication channel to which this trigger applies."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false,
            "description": "Event or schedule that starts this rule; the fields depend on type.",
            "examples": [
              {
                "type": "on_update",
                "resource_type": "core:Deal",
                "fields": [
                  "stage"
                ]
              }
            ]
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether new matching events can start this rule. It does not report the outcome of past runs.",
            "examples": [
              true
            ]
          },
          "locked": {
            "type": "boolean",
            "description": "Built-in: neither disabled nor deleted.",
            "examples": [
              false
            ]
          },
          "scope": {
            "type": "string",
            "description": "`org` for an org-level rule, `mine` for the caller's own.",
            "examples": [
              "org"
            ]
          },
          "can_manage": {
            "type": "boolean",
            "description": "Whether the acting member can manage this rule. Locked built-in rules cannot be disabled or deleted.",
            "examples": [
              true
            ]
          },
          "created_at": {
            "type": "number",
            "description": "Creation time in Unix milliseconds."
          },
          "last_run": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "run_id": {
                "type": "string",
                "description": "Run identifier."
              },
              "rule_id": {
                "type": "string",
                "description": "Rule identifier."
              },
              "app_id": {
                "type": "string",
                "description": "App identifier."
              },
              "trigger_type": {
                "type": "string",
                "description": "Trigger category identifying how the automation starts."
              },
              "status": {
                "type": "string",
                "description": "`ok` / `partial` / `error` / `skipped` — the roll-up over the rule's actions."
              },
              "fired_at": {
                "type": "number",
                "description": "Time of this trigger activation, in Unix milliseconds."
              }
            },
            "additionalProperties": false,
            "description": "Most recent execution summary, or null if the rule has never run.",
            "examples": [
              null
            ]
          }
        },
        "required": [
          "rule_id",
          "app_id",
          "enabled",
          "locked",
          "scope",
          "can_manage",
          "created_at",
          "last_run"
        ],
        "additionalProperties": false,
        "title": "Automation rule"
      },
      "description": "Rules visible to the acting member, optionally restricted to app_id and bounded by limit. This operation has no cursor pagination."
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "items": [
        {
          "rule_id": "rule_follow_up",
          "app_id": "core",
          "description": "Create a follow-up task when a deal changes stage.",
          "trigger": {
            "type": "on_update",
            "resource_type": "core:Deal",
            "fields": [
              "stage"
            ]
          },
          "enabled": true,
          "locked": false,
          "scope": "org",
          "can_manage": true,
          "created_at": 1794301200000,
          "last_run": {
            "run_id": "run_follow_up_1",
            "rule_id": "rule_follow_up",
            "app_id": "core",
            "trigger_type": "on_update",
            "status": "error",
            "fired_at": 1794387600000
          }
        }
      ]
    }
  ]
}
```