Skip to main content
GET
Read a project

Authorizations

Authorization
string
header
required

A Motion API key. Access is limited to its stored organization, workspace, scopes and the creator’s current permissions.

Scopes

motion:sessions:read

Read permitted chats, job status and saved exports.

Path Parameters

id
string<uuid>
required

Query Parameters

limit
integer
default:25

Page size for both messages and generations.

Required range: 1 <= x <= 100
cursor
string

next_cursor from the preceding generation page.

after_sequence
integer

Read messages after this sequence number.

Required range: x >= 0
include_explanations
boolean
default:false

Include user-visible progress explanations.

Response

Success

id
string<uuid>
required

Motion project UUID. Use it to read, continue or export this project.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
title
string | null
required

Project title displayed in Motion, or null before a title is assigned.

status
enum<string>
required

Project work status. Completed means the agent finished; exports may still be preparing.

Available options:
queued,
running,
completed,
failed,
cancelled,
awaiting_user_input,
awaiting_credits
created_at
string<date-time>
required

Project creation time.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_at
string<date-time>
required

Time the project record was last updated.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
chat_url
string<uri>
required

Motion web chat URL where the user can inspect and continue this project.

effort
enum<string>
required

Project effort fixed at creation. Follow-ups, steering and resumed turns keep this choice.

Available options:
standard,
extended
connectors
object[] | null
required

Connections available to this project. null uses the default selection; [] disables connectors.

export_formats
enum<string>[]
required

Current automatic export settings. Each turn uses these unless its message changes them. [] disables automatic exports.

Available options:
mp4,
png,
jpeg,
media,
premiere,
after-effects,
resolve,
final-cut,
psd,
svg
Example:
messages
object[]
required

User and assistant messages in conversation order.

messages_has_more
boolean
required

More messages are available.

messages_next_after_sequence
integer | null
required

Pass as after_sequence to read the next message page.

Required range: 0 <= x <= 9007199254740991
generations
object[]
required

Saved project versions, each containing one or more compositions.

exports
object[]
required

Exports from the API and app. Each includes its format, status and download when ready.

Maximum array length: 25
exports_has_more
boolean
required

More exports are available.

exports_next_cursor
string | null
required

Pass as cursor to list_project_exports to read more.

has_more
boolean
required

True when another page is available.

next_cursor
string | null
required

Opaque cursor for the next page, or null at the end. Pass it unchanged as cursor.