Get an automation
Platform module
GET/automations/{id}automations.get
An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Returns one automation with its `ETag`. A automation the caller may not see returns 404.
- Requires the capability org.automations.write.
- OAuth scopes: org.
- Error statuses: 400, 401, 404, 429. Errors are RFC 9457 problem details.
Path and query parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the automation. |
| fields | Fields | No | Sparse fieldset: a comma-separated list of top-level fields to return. `id` is always returned.Constraints: pattern ^[a-z_][a-z0-9_]*(,[a-z_][a-z0-9_]*)*$ |
Response 200: Automation
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the automation. |
| org_id | string (uuid) | Yes | Identifier of the owning organization, derived from the parent row and never accepted from the caller. |
| created_at | string (date-time) | Yes | When the row was created. |
| created_by | string (uuid) | null | Yes | Identifier of the person who created the row. |
| updated_at | string (date-time) | Yes | When the row was last updated. |
| updated_by | string (uuid) | null | Yes | Identifier of the person who last updated the row. |
| name | string | Yes | Name shown in Settings, Automations.Constraints: length 1 to 120 |
| description | string | null | Yes | What the automation is for.Constraints: length 1 to 500 |
| trigger_event_type | string | Yes | Domain event type that starts a run, from the catalog webhooks use (webhookEventTypes.list).Constraints: pattern ^[a-z][a-z_]*\.[a-z][a-z_]*$ |
| condition_match | "all" | "any" | Yes | How the top-level conditions combine; set from the conditions document. |
| owner_person_id | string (uuid) | Yes | Identifier of the person the actions run as. |
| enabled | boolean | Yes | True while new events start runs. |
| paused_at | string (date-time) | null | Yes | When the engine turned the automation off because a run could not act as the owner; null otherwise. Turning it on again clears it. |
| pause_reason | string | null | Yes | Why the engine paused it: owner_left_org, owner_lost_capability, owner_cannot_sign_in or owner_access_refused.Constraints: pattern ^[a-z][a-z0-9_]*$ |
| conditions | AutomationConditions | Yes | An automation's conditions: {"all": [...]} or {"any": [...]} of conditions and one-level groups, at most 20 in all. An empty list always holds. |
| actions | AutomationActions | Yes | An automation's 1 to 10 actions, in the order they run. |
{
"id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"created_at": "2026-10-08T14:30:00Z",
"created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"updated_at": "2026-10-08T14:30:00Z",
"updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"name": "Pick up new tasks",
"description": "Comments on every new task.",
"trigger_event_type": "record.created",
"condition_match": "all",
"owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"enabled": true,
"paused_at": "2026-10-08T14:30:00Z",
"pause_reason": "owner_left_org",
"conditions": {
"all": [
{
"field": "data.record_kind",
"operator": "eq",
"value": "Task"
}
]
},
"actions": [
{
"type": "add_comment",
"body": "Picked up {{data.title}}."
}
]
}Code samples
curl -X GET "$XOS_BASE_URL/automations/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" \
-H "Authorization: Bearer $XOS_API_KEY"const { data, etag } = await xos.automations.get("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f");response = xos.automations.get("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f")xos automations get 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f