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

# Get Motion

> Retrieve the current state of one Motion.

`GET /v1/motions/{motion_id}` retrieves a Motion. Poll while its status is `queued` or `processing`.

## Request parameters

| Parameter   | Type   | Required | Description                                                                |
| ----------- | ------ | :------: | -------------------------------------------------------------------------- |
| `motion_id` | string |    Yes   | Full Motion ID beginning with `mot_`, returned by Create or Import Motion. |

## Response parameters

Returns `200 OK` with a Motion object.

| Field          | Type            | Always present | Description                                         |
| -------------- | --------------- | :------------: | --------------------------------------------------- |
| `id`           | string          |       Yes      | The requested public Motion ID.                     |
| `status`       | string          |       Yes      | `queued`, `processing`, `ready`, or `failed`.       |
| `name`         | string          |       Yes      | Motion label, or an empty string.                   |
| `progress`     | integer or null |       Yes      | Progress from 0 to 100 when available.              |
| `capabilities` | string\[]       |       Yes      | `video_render` after the Motion is ready.           |
| `created_at`   | string or null  |       Yes      | ISO 8601 creation timestamp.                        |
| `completed_at` | string or null  |       Yes      | ISO 8601 completion timestamp; null until complete. |
| `error`        | object or null  |       Yes      | Failure details when status is `failed`.            |

```json theme={null}
{"id":"mot_456def","status":"ready","name":"Dance loop","progress":100,"capabilities":["video_render"],"created_at":"2026-07-21T10:00:00Z","completed_at":"2026-07-21T10:00:20Z","error":null}
```

## Examples

<CodeGroup>
  ```go Go theme={null}
  id := "mot_456def"; req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/motions/"+id, nil); req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); resp, err := http.DefaultClient.Do(req); if err != nil { panic(err) }; defer resp.Body.Close()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/v1/motions/mot_456def", {headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}}); const motion = await response.json();
  ```

  ```python Python theme={null}
  import os, requests
  response=requests.get("https://apis.viggle.ai/v1/motions/mot_456def",headers={"Authorization":f"Bearer {os.environ['VIGGLE_API_KEY']}"}); response.raise_for_status(); motion=response.json()
  ```

  ```bash cURL theme={null}
  curl "https://apis.viggle.ai/v1/motions/mot_456def" -H "Authorization: Bearer $VIGGLE_API_KEY"
  ```
</CodeGroup>


## OpenAPI

````yaml GET /v1/motions/{motion_id}
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security: []
paths:
  /v1/motions/{motion_id}:
    get:
      summary: Get Motion
      operationId: v1GetMotion
      responses:
        '200':
          description: Motion

````