> ## 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.

# List projects

> List your projects in this workspace.



## OpenAPI

````yaml /openapi.json get /projects
openapi: 3.1.0
info:
  title: Motion
  version: 1.1.0
  description: >-
    Create Motion projects from prompts, read authored generations and outputs,
    and explicitly request renders or editor exports. Use reusable templates and
    brand kits. Credentials remain bound to current workspace access and
    permissions. Legacy single-video endpoints are deprecated.
servers:
  - url: https://api.motion.so/api/motion
security:
  - MotionApiKey: []
tags:
  - name: Projects
  - name: Project results
  - name: Project exports
  - name: Templates
  - name: Brand kits
  - name: Media library
  - name: Automations
  - name: Social posting
  - name: API information
  - name: Deprecated endpoints
    description: >-
      Older single-video routes remain callable for existing clients. Use the
      project API for new integrations; no removal date is scheduled.
  - name: Connectors
    description: Connect services and control the actions a project may use.
paths:
  /projects:
    get:
      tags:
        - Projects
      summary: List projects
      description: List your projects in this workspace.
      operationId: ListProjects
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
            maxLength: 200
          description: Match project titles and available legacy saved prompt context.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionListProjectsResponse'
              example:
                projects:
                  - id: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                    title: Product launch
                    status: completed
                    created_at: '2026-11-17T20:00:00Z'
                    updated_at: '2026-11-17T20:00:00Z'
                    chat_url: >-
                      https://motion.so/agent?chat=4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                has_more: false
                next_cursor: null
        '400':
          description: Invalid input or cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Credential invalid or revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing scope, role, resource access or entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Stale revision, active work or conflicting source identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required service unavailable; do not blindly retry mutations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - MotionApiKey: []
        - MotionOAuth:
            - motion:sessions:read
components:
  schemas:
    MotionListProjectsResponse:
      type: object
      properties:
        projects:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: >-
                  Motion project UUID. Use this ID to read or continue the
                  project.
              title:
                type:
                  - string
                  - 'null'
                description: >-
                  Project title displayed in Motion, or null before a title is
                  assigned.
              status:
                type: string
                enum:
                  - queued
                  - running
                  - completed
                  - failed
                  - cancelled
                  - awaiting_user_input
                  - awaiting_credits
                description: >-
                  Project work status. Completed means the agent finished;
                  exports may still be preparing.
              created_at:
                type: string
                format: date-time
                description: Project creation time as an ISO 8601 timestamp.
              updated_at:
                type: string
                format: date-time
                description: >-
                  Time the project record was last updated, as an ISO 8601
                  timestamp.
              chat_url:
                type: string
                format: uri
                description: >-
                  Motion web chat URL where the user can inspect and continue
                  this project.
            required:
              - id
              - title
              - status
              - created_at
              - updated_at
              - chat_url
            additionalProperties: false
          description: >-
            Projects owned by this account in the credential workspace, ordered
            by most recent update. Each project is a Motion conversation and its
            saved work.
        has_more:
          type: boolean
          description: True when another page is available.
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Opaque cursor for the next page, or null at the end. Pass it
            unchanged as cursor.
      required:
        - projects
        - has_more
        - next_cursor
      additionalProperties: false
    ErrorResponse:
      type: object
      description: >-
        Error bodies are JSON. Check the HTTP status first. Permission and
        validation errors use error; service errors may use detail. Optional
        fields explain how to correct the request.
      anyOf:
        - required:
            - error
        - required:
            - detail
      properties:
        error:
          type: string
          description: Error code or readable explanation.
        detail:
          type: string
          description: Readable explanation from the service.
        message:
          type: string
          description: Readable explanation accompanying an error code.
        error_description:
          type: string
          description: Authentication or permission explanation.
        required_scope:
          type: string
          description: Permission required by this operation.
        details:
          type: array
          description: Invalid request fields. Each issue includes a path and message.
          items:
            type: object
            properties:
              code:
                type: string
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
              message:
                type: string
        issues:
          type: array
          description: Service validation issues.
          items:
            type: object
  securitySchemes:
    MotionApiKey:
      type: http
      scheme: bearer
      description: >-
        A Motion API key. Access is limited to its stored organization,
        workspace, scopes and the creator’s current permissions.
    MotionOAuth:
      type: oauth2
      description: >-
        OAuth REST tokens use the full MCP audience, https://mcp.motion.so/mcp.
        Reauthorize existing connections to add scopes. Current workspace roles
        and resource permissions still apply.
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.motion.so/oauth/authorize
          tokenUrl: https://mcp.motion.so/oauth/token
          scopes:
            motion:automations:read: Read automation definitions, capabilities, runs, and analytics.
            motion:automations:write: Create, edit, delete, invoke, and retry automations.
            motion:connectors:read: >-
              Read available services, your private organization connections and
              allowed actions without secrets.
            motion:connectors:write: >-
              Connect and disconnect your private accounts inside the credential
              organization workspace.
            motion:templates:read: Read and preview accessible templates.
            motion:templates:write: Create, edit, share, and archive prompt templates.
            motion:sessions:read: Read permitted chats, job status and saved exports.
            motion:sessions:write: >-
              Create and steer Motion projects using organization workspace
              credits.
            motion:assets:read: Find and read permitted media library assets.
            motion:brand-kits:read: Read permitted brand kits.
            motion:brand-kits:write: Create and edit brand kits within current app permissions.
            motion:social:read: Read authorized social accounts and posts.
            motion:social:write: >-
              Draft, submit, approve and cancel posts within current app
              permissions.

````

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