---
title: "Create a followup for a completed or input-awaiting video job"
method: POST
path: "/sessions/{job_id}/followups"
---

# Create a followup for a completed or input-awaiting video job

`POST /sessions/{job_id}/followups`

## Request

- Base URL: `https://api.motion.so/api/motion`
- URL: `https://api.motion.so/api/motion/sessions/{job_id}/followups`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/motion/apis/mosaic-motion/docs/sessions/:job_id/followups/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `job_id` string, required

## Request body

- CreateMotionSessionRequest: Creates a durable video job owned by the API key user. Requires available Motion credits on that user's account. Credits and auto top-ups are managed at https://motion.so, not through the API.
  - `prompt` string, required
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:5' | '21:9': Target video aspect ratio.
  - `duration` '<10s' | '10-30s' | '30s-1min' | '1-5min': Target video duration bucket.
  - `design_system_id` 'mosaic' | 'apple' | 'claude' | 'cursor' | 'linear' | 'vercel' | 'stripe' | 'figma' | 'notion' | 'spotify' | 'supabase' | 'raycast' | 'framer' | 'resend' | 'mintlify' | 'sentry' | 'tesla' | 'nike' | 'shopify' | 'airbnb' | 'posthog': Pro/Max built-in DESIGN.md preset to apply.
  - `design_md` union: Pro/Max custom DESIGN.md content, optionally with a companion style extraction JSON artifact. If both design_system_id and design_md are sent, design_md content is used.
    - string
    - MotionDesignMd
      - `filename` string
      - `sourceUrl` string: Optional source website URL for imported style extraction context.
      - `content` string, required: Pro/Max markdown design system guidance saved as DESIGN.md for the job.
      - `jsonFilename` string: Optional companion style extraction JSON filename.
      - `jsonContent` string: Optional structured style extraction JSON saved alongside DESIGN.md for agent context.
  - `style_reference_url` string, uri: Optional YouTube style reference URL.
  - `attachments` MotionAttachment[]
    - `url` string, uri, required: Publicly accessible signed URL.
    - `name` string
    - `type` 'image' | 'video' | 'audio' | 'file'
    - `content_type` string
  - `engine` string: Video engine. New jobs default to gva. Motion Legacy requires eligible account access. Use GET /engines for available choices. Mode-only requests select Motion and require Legacy access.
  - `effort` 'standard' | 'extended' | 'light' | 'medium' | 'high': GVA: standard (default) or extended. Motion: light, medium (default), or high. Legacy GVA light/medium map to standard; high maps to extended. Follow-ups retain the current effort when omitted.
  - `mode` 'light' | 'medium' | 'high': Alias for effort. Mode-only creation selects Motion. Must resolve to the same effort if both are supplied. For GVA, light/medium map to standard and high maps to extended.
  - `template` string: Identifier from the selected engine template catalog. Set at creation; requires Pro or Max.

## Response `202`

Followup accepted

- CreateMotionSessionResponse
  - `job_id` string, required
  - `status` 'queued', required
  - `status_url` string, uri, required: Authenticated public API polling URL for GET /sessions/{job_id}. This is not a Motion app page.
  - `chat_url` string, uri, nullable: Motion app chat URL for a human to open, inspect, or continue the run. Null only for legacy flows where no chat is available.
  - `engine` string, nullable: Null when engine details are unavailable to this account.
  - `effort` 'standard' | 'extended' | 'light' | 'medium' | 'high' | 'null', nullable: Null when engine details are unavailable to this account.
  - `template` string, nullable

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid Motion API key
- `402`: The job is paused for credits and cannot resume until enough credits are available.
- `403`: The account lacks access to the selected or persisted engine. No generation starts.
- `404`: Job not found or not owned by API key user
- `409`: Followups are only allowed for completed or input-awaiting jobs

## Changes

- **2026-10-20** `075b364b747d`: 2 breaking, 1 warning
  - the response property `effort` became nullable for the status `202`
  - the response property `engine` became nullable for the status `202`
  - added the new `undefined` enum value to the `effort` response property for the response status `202`
- **2026-10-14** `a16a13fa90ea`: 5 breaking, 3 info
  - removed the enum value `gva` of the request property `engine`
  - removed the enum value `kai` of the request property `engine`
  - removed the enum value `mira` of the request property `engine`
  - removed the enum value `motion` of the request property `engine`
  - …4 more
- **2026-10-08** `dfb50f1ab8d4`: 9 info
  - added the new optional request property `effort`
  - added the new optional request property `engine`
  - added the new optional request property `mode`
  - added the new optional request property `template`
  - …5 more

[Operation history](https://skmtc.dev/motion/apis/mosaic-motion/changes/sessions/:job_id/followups/post.md)

---

[API](https://skmtc.dev/motion/apis/mosaic-motion.md) - [All operations](https://skmtc.dev/motion/apis/mosaic-motion/llms.txt) - [OpenAPI document](https://skmtc.dev/motion/apis/mosaic-motion/revisions/075b364b747d?raw)