> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Automations

> Create schedules and channel automations, manage run history, and inspect results through REST or MCP.

Save instructions once and run them on a schedule or when a channel event arrives. Manage the same automations in [Motion](https://motion.so), through REST, or through any Motion MCP profile.

Automations require Pro, Max, Enterprise, or an existing unlimited entitlement, and must be enabled in the server environment. A key, OAuth grant, or credit balance does not enable automation or engine access. Read requests do not start work or spend credits. Invocations create new Motion chats and can use your account's credits.

## Authentication and discovery

Use an owner account's `motion_` API key. For OAuth, REST requires a token issued for `https://mcp.motion.so/mcp`; tokens issued for restricted MCP profiles cannot be reused for REST.

* `motion:automations:read`: capabilities, definitions, run history, and analytics.
* `motion:automations:write`: create, edit, pause, resume, delete, run, and retry.

Existing session scopes do not grant automation access. Reauthorize an existing OAuth connection to add the needed scopes. API keys use account permissions without OAuth scopes. See [Authentication](https://docs.motion.so/guides/authentication.md).

```bash theme={null}
export MOTION_API_KEY="motion_your_api_key"
export MOTION_API_BASE="https://api.motion.so/api/motion"

curl "$MOTION_API_BASE/automations/capabilities" \
  -H "Authorization: Bearer $MOTION_API_KEY"
```

The response lists `triggers`, supported `operations`, `execution_engine: "gva"`, `default_effort: "standard"`, `execution_supported`, `update_constraints`, `run_destination: "new_chat"`, and `schedule_semantics: "elapsed_minutes"`. Read capabilities before choosing a trigger. Available types are one-time and recurring schedules, YouTube uploads, and Twitch or Kick stream endings when the environment supports them. Availability does not confirm a channel subscription is active; inspect the saved automation's `triggerSubscription` for readiness and delivery errors.

## Create a recurring automation

```bash theme={null}
curl "$MOTION_API_BASE/automations" \
  -H "Authorization: Bearer $MOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily product animation",
    "prompt": "Create a 10-second animation from code with the title Daily update, a navy background, and mint typography.",
    "trigger": {
      "type": "schedule_recurring",
      "platform": "schedule",
      "label": "Every 24 hours",
      "source": "Schedule",
      "intervalMinutes": 1440
    },
    "execution": {"engine": "gva", "effort": "standard"},
    "outputKind": "video"
  }'
```

HTTP `201` returns `{ "automation": ... }`. Save its `id`. The automation starts enabled; its first scheduled run follows the configured interval. Creation is not idempotent. If the response is lost, list your automations before creating another definition.

`name`, `prompt`, and `trigger` are required. Write a self-contained prompt for future runs. Defaults are GVA standard, video output, one concurrent run, and four runs per hour. Default memory remembers processed items, includes five previous runs, and compacts after 20 runs. Connector access defaults to none.

Recurring schedules use elapsed minutes, from 1 to 525600. They do not interpret cron expressions or a local daily clock time. `timezone` is display metadata. For a one-time schedule, use `type: "schedule_once"`, `platform: "schedule"`, and a future `runAt` timestamp with an explicit UTC offset.

Automations execute only with GVA and default to `standard` effort. Choose `extended` for more demanding work. Motion is a Legacy video engine and is not available for automation execution. Discover engine access through `GET /engines` or `list_engines`. Saved runs retain their execution snapshot after later definition edits.

For channel triggers, match the platform and type, and set `source` to the channel URL, handle, or YouTube channel ID. New uploads or stream events supply the source context. A manual run cannot substitute for a channel event.

Optional `connectorPolicy` supports existing read connections to GitHub, Notion, Figma, Google Drive, Dropbox, and Getty. It cannot grant account access. Each grant has `connectorId`, `access: "read"`, and `resources` (up to 50). Use `mode: "none"`, `"fixed"`, or `"conditional"` and `onUnavailable: "block"` or `"run_without"`. See the [create reference](https://docs.motion.so/reference/create-automation.md) for conditions and field bounds.

## Run and inspect a result

Only schedule automations support manual runs. Use a new UUID for each intentional invocation and reuse it if the HTTP response is lost:

```bash theme={null}
export AUTOMATION_ID="ID_FROM_CREATE"
export RUN_REQUEST_ID="$(uuidgen)"

curl -X POST "$MOTION_API_BASE/automations/$AUTOMATION_ID/run" \
  -H "Authorization: Bearer $MOTION_API_KEY" \
  -H "Idempotency-Key: $RUN_REQUEST_ID"
```

A new invocation returns HTTP `202`; a repeated UUID returns HTTP `200` and `deduplicated: true`. The response includes `automation`, `run`, and `session`. Keep the run ID and read it with `GET /automations/{automation_id}/runs/{run_id}`. States are `queued`, `running`, `completed`, `skipped`, `failed`, and `blocked`.

`run.motionAgentChatId` is null until a chat is created. Once present, open `https://motion.so/agent?chat={motionAgentChatId}` to inspect and continue the work. A completed agent invocation does not guarantee a finished video export. Read that chat's saved exports with `list_chat_exports` and `get_chat_export`, or inspect its exports in Motion, to retrieve a fresh download link.

## Edit, pause, resume, and delete

```bash theme={null}
curl -X PATCH "$MOTION_API_BASE/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $MOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
```

Use `enabled: true` to resume. Pausing stops future scheduling; it does not cancel work already running. `DELETE /automations/{automation_id}` deletes the definition and also does not cancel a running Motion chat.

PATCH accepts `name`, `prompt`, `trigger`, `memory`, `connectorPolicy`, `maxConcurrentRuns`, `maxRunsPerHour`, `execution`, and `enabled`. Nested objects replace their saved value, so include all required fields within each object. `outputKind` is creation-only. Read-view fields such as owner, destination, and worker policy are not write inputs.

If an execution edit returns `409 update_conflict`, another edit changed its saved execution settings. Read the automation again before retrying your edit.

## Pagination, retry, and analytics

`GET /automations` accepts `limit` (1–100, default 50), `search`, `enabled`, and `cursor`. Results sort by creation time descending, then ID. Pass `next_cursor` to the next request with the same filters until `has_more` is false. Keep the cursor opaque.

Run history uses `GET /automations/{automation_id}/runs`. This response returns `runs`, `total`, and **`nextCursor`**. Pass `nextCursor` as the next request's `cursor`; stop when it is null. Run-history and definition-list cursor fields use different casing.

Retry a `failed` or `blocked` invocation with `POST /automations/{automation_id}/runs/{run_id}/retry`, without a body. This uses the original event and returns HTTP `202`. Repeating the failed run ID returns its existing replacement attempt rather than creating another one. A paused automation must be resumed first. Channel automation retries preserve the actual source event.

`GET /automations/{automation_id}/analytics?days=30` returns `days`, `total`, and daily `buckets` containing `completed`, `failed`, `skipped`, `inProgress`, and `total`. The window is 7–90 days and defaults to 30.

## MCP tools and Claude

All five profiles (full, directory, OpenAI, Muse, and Claude) expose these tools when the account and scopes allow them:

| Tool | REST equivalent |
| - | - |
| `get_automation_capabilities` | `GET /automations/capabilities` |
| `list_automations` | `GET /automations` |
| `get_automation` | `GET /automations/{automation_id}` |
| `create_automation` | `POST /automations` |
| `update_automation` | `PATCH /automations/{automation_id}` |
| `delete_automation` | `DELETE /automations/{automation_id}` |
| `run_automation` | `POST /automations/{automation_id}/run` |
| `list_automation_runs` | `GET /automations/{automation_id}/runs` |
| `get_automation_run` | `GET /automations/{automation_id}/runs/{run_id}` |
| `retry_automation_run` | `POST /automations/{automation_id}/runs/{run_id}/retry` |
| `get_automation_analytics` | `GET /automations/{automation_id}/analytics` |

MCP uses the same definition fields as REST. For existing records, pass `automation_id`; run-detail and retry tools also take `run_id`. `run_automation` takes a UUID **`request_id`** in its tool arguments instead of the REST header. Read the connected profile's schema for permitted engines and efforts.

Claude can read, pause, or delete your existing automations. Automation creation, other edits, resuming, running, and retrying require a GVA-capable connector or the [Motion app](https://motion.so). The Claude connector uses the Legacy Motion engine for video work and cannot execute GVA automations. See [Motion for Claude](https://docs.motion.so/guides/claude.md).

## Errors

Automation errors return `{ "error": "code", "message": "readable explanation" }`. HTTP `403 insufficient_scope` requires OAuth reauthorization; `403 access_denied` means automation access is not enabled for the account. `404 unavailable` means the environment does not expose automations. A missing record or one owned by another user returns `404 not_found`.

`400 invalid_input` describes the field to correct, `400 unavailable_trigger` means the selected trigger is unavailable, and `409 automation_paused` requires resuming before an invocation. Retry `503 temporarily_unavailable` later. See [Errors](https://docs.motion.so/guides/errors.md) and the [OpenAPI schema](https://docs.motion.so/openapi.json).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.