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

> Get scene details by ID

Pulls up everything about a single scene — the video details (duration, fps, resolution) plus where it is in processing. This is the endpoint you'll poll after [creating](/api-reference/scenes/create) or [importing](/api-reference/scenes/import) a scene.

<Note>
  Check back every 5 seconds or so until `status` turns `ready` or `failed`.
</Note>

## Path parameters

| Parameter  | Type   | Required | Description                                              |
| ---------- | ------ | :------: | -------------------------------------------------------- |
| `scene_id` | string |     ✅    | The scene UUID returned when you created or imported it. |

## Response

```json theme={null}
{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "Dance Sequence",
  "status": "ready",
  "duration_seconds": 6.67,
  "fps": 30.0,
  "total_frames": 200,
  "width": 1920,
  "height": 1080,
  "credits_used": 6.67,
  "created_at": "2026-06-12T08:00:00Z",
  "completed_at": "2026-06-12T08:01:10Z"
}
```

| Field                                       | Description                                                           |
| ------------------------------------------- | --------------------------------------------------------------------- |
| `status`                                    | `pending`, `ready`, or `failed`. Only `ready` scenes can be rendered. |
| `duration_seconds` / `fps` / `total_frames` | Timing metadata extracted from the driving video.                     |
| `width` / `height`                          | Source video resolution in pixels.                                    |
| `error_message`                             | Why processing failed. Present only when `status` is `failed`.        |

## Example

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

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

  response = requests.get(url, headers=headers)
  response.raise_for_status()
  result = response.json()

  print(f"Name: {result['name']}")
  print(f"Status: {result['status']}")
  ```

  ```javascript JavaScript theme={null}
  const sceneId = "YOUR_SCENE_ID";

  const response = await fetch(`https://apis.viggle.ai/api/scenes/${sceneId}`, {
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const result = await response.json();
  console.log(`Name: ${result.name}`);
  console.log(`Status: ${result.status}`);
  ```

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

## Next steps

Once `status` is `ready`, use the scene's `id` as `scene_id` in a [render job](/api-reference/render/create).


## OpenAPI

````yaml GET /api/scenes/{scene_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:
  /api/scenes/{scene_id}:
    get:
      tags:
        - Scenes
      summary: Get Scene
      description: >-
        Get full details of a specific scene including video metadata and
        processing status.
      operationId: getScene
      parameters:
        - name: scene_id
          in: path
          required: true
          schema:
            type: string
          example: 660e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Scene details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scene'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Scene not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorStructured'
              example:
                detail:
                  error_code: CS-UORC01-003
                  message: Scene not found. Double-check the scene_id.
      security:
        - bearerAuth: []
components:
  schemas:
    Scene:
      type: object
      properties:
        id:
          type: string
          example: 660e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: Dance Sequence
        status:
          type: string
          enum:
            - pending
            - ready
            - failed
        duration_seconds:
          type: number
          nullable: true
          example: 6.67
        fps:
          type: number
          nullable: true
          example: 30
        total_frames:
          type: integer
          nullable: true
          example: 200
        width:
          type: integer
          nullable: true
          example: 1920
        height:
          type: integer
          nullable: true
          example: 1080
        job_id:
          type: string
          nullable: true
          example: scene_660e8400e29b
        error_message:
          type: string
          nullable: true
        credits_used:
          type: number
          nullable: true
          example: 6.67
        created_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    ErrorStructured:
      type: object
      description: >-
        Structured error. `detail` carries a machine-readable `error_code` plus
        a human-readable `message`.
      properties:
        detail:
          type: object
          properties:
            error_code:
              type: string
              example: CS-UORC01-008
            message:
              type: string
              example: Insufficient credits. Top up your balance to continue.
    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

````