# Automations

> Check how automations are running, and start the ones that are started by hand.

## Check on automations

With `automations:read`:

| Call | Returns |
| --- | --- |
| `GET /v1/automations?project_id=PROJECT_ID` | Automations you can see, each with its trigger and a one-sentence summary |
| `GET /v1/automations/AUTOMATION_ID` | One automation |
| `GET /v1/automations/AUTOMATION_ID/runs` | Its recent runs, newest first |
| `GET /v1/automation-runs/RUN_ID` | One run, with every step it took and where it stopped or failed |

A failed run has an `error`, and its steps show which one failed. That makes a simple monitor easy: list recent runs every few minutes and alert on new failures.

## Start one from your code

Automations whose trigger is **Started by hand** have `startable: true`. These can be started with `automations:write`, for example from a form submission or another system's webhook.

### Start it

```bash
curl -X POST https://developers.playbookops.ai/v1/automations/AUTOMATION_ID/runs \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"item_id": "ITEM_ID"}'
```

If the automation has `needs_item: true`, pass the `item_id` to run it on. An app's automation takes a `record_id` instead.

### Follow the run

The answer is the new run. Check on it with `GET /v1/automation-runs/RUN_ID` until it has a `finished_at`, then look at its `status`, its `error` if it failed, and its steps.

> **Only published automations that are on**
> The automation must be published and switched on. Automations with any other trigger start on their own, and starting them returns `400`.

## Reference

| Action | Endpoint | MCP tool |
| --- | --- | --- |
| List automations | `GET /v1/automations` | `list_automations` |
| One automation | `GET /v1/automations/{id}` | `get_automation` |
| Its runs | `GET /v1/automations/{id}/runs` | `list_automation_runs` |
| One run | `GET /v1/automation-runs/{id}` | `get_automation_run` |
| Start one | `POST /v1/automations/{id}/runs` | `start_automation` |

Every parameter is in the [API reference](https://developers.playbookops.ai/reference/automations).
