Automations

Save instructions once and run them on a schedule or when a channel event arrives. Manage the same automations in Motion, 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.

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

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 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:

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

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. The Claude connector uses the Legacy Motion engine for video work and cannot execute GVA automations. See Motion for Claude.

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 and the OpenAPI schema.

Getting Started

AI Agents

Guides

Authentication and discovery

Create a recurring automation

Run and inspect a result

Edit, pause, resume, and delete

MCP tools and Claude

Errors

​Authentication and discovery

​Create a recurring automation

​Run and inspect a result

​Edit, pause, resume, and delete

​Pagination, retry, and analytics

​MCP tools and Claude

​Errors

Authentication and discovery

Create a recurring automation

Run and inspect a result

Edit, pause, resume, and delete

Pagination, retry, and analytics

MCP tools and Claude

Errors