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

# List Scenes

> List all scenes for your account

Lists all the scenes on your account, newest first. Use it to grab a scene's `id` for rendering, or to see which ones have finished processing and are `ready` to go.

Got a lot of scenes? Page through them with `limit` and `offset`.

## Query parameters

| Parameter | Type    | Default | Description                               |
| --------- | ------- | ------- | ----------------------------------------- |
| `limit`   | integer | `50`    | Max scenes to return (1–100).             |
| `offset`  | integer | `0`     | Number of scenes to skip, for pagination. |

## Response

```json theme={null}
{
  "scenes": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Dance Sequence",
      "status": "ready",
      "duration_seconds": 6.67,
      "created_at": "2026-06-12T08:00:00Z",
      "completed_at": "2026-06-12T08:01:10Z"
    }
  ],
  "total": 1
}
```

| Field                       | Description                                          |
| --------------------------- | ---------------------------------------------------- |
| `scenes[]`                  | The page of scenes, newest first.                    |
| `scenes[].id`               | Scene UUID — pass this as `scene_id` when rendering. |
| `scenes[].status`           | `pending`, `ready`, or `failed`.                     |
| `scenes[].duration_seconds` | Length of the source video.                          |
| `total`                     | Number of scenes returned in this page.              |

## Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://apis.viggle.ai/api/scenes"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  response = requests.get(url, headers=headers, params={"limit": 50, "offset": 0})
  response.raise_for_status()
  result = response.json()

  for scene in result["scenes"]:
      print(f"{scene['id']}: {scene['name']} ({scene['status']})")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/api/scenes?limit=50&offset=0", {
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const result = await response.json();
  result.scenes.forEach((scene) => {
    console.log(`${scene.id}: ${scene.name} (${scene.status})`);
  });
  ```

  ```bash cURL theme={null}
  curl -X GET "https://apis.viggle.ai/api/scenes?limit=50&offset=0" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## Next steps

Pick a scene whose `status` is `ready` and use its `id` as `scene_id` in a [render job](/api-reference/render/create). To inspect one scene, call [Get Scene](/api-reference/scenes/get).


## OpenAPI

````yaml GET /api/scenes
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:
  /api/scenes:
    get:
      tags:
        - Scenes
      summary: List Scenes
      description: >-
        List all scenes for the authenticated user, ordered by most recent
        first.
      operationId: listScenes
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Paginated list of scenes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SceneList'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
components:
  schemas:
    SceneList:
      type: object
      properties:
        scenes:
          type: array
          items:
            $ref: '#/components/schemas/SceneListItem'
        total:
          type: integer
          description: Total number of scenes returned
    SceneListItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - pending
            - ready
            - failed
        duration_seconds:
          type: number
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      description: >-
        Simple error. `detail` is a human-readable message (used for auth
        errors).
      properties:
        detail:
          type: string
          example: 'API key required. Use Authorization: Bearer sk-xxx'
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Invalid or missing API key. Pass it as Authorization: Bearer
              sk-...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````