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

> List all characters for your account

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

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

## Query parameters

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

## Response

```json theme={null}
{
  "characters": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Character",
      "status": "ready",
      "created_at": "2026-06-12T08:00:00Z",
      "completed_at": "2026-06-12T08:00:42Z"
    }
  ],
  "total": 1
}
```

| Field                 | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `characters[]`        | The page of characters, newest first.                        |
| `characters[].id`     | Character UUID — pass this as `character_id` when rendering. |
| `characters[].status` | `pending`, `processing`, `ready`, or `failed`.               |
| `total`               | Number of characters returned in this page.                  |

## Example

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

  url = "https://apis.viggle.ai/api/characters"
  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 character in result["characters"]:
      print(f"{character['id']}: {character['name']} ({character['status']})")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/api/characters?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.characters.forEach((character) => {
    console.log(`${character.id}: ${character.name} (${character.status})`);
  });
  ```

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

## Next steps

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


## OpenAPI

````yaml GET /api/characters
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/characters:
    get:
      tags:
        - Characters
      summary: List Characters
      description: >-
        List all characters for the authenticated user, ordered by most recent
        first.
      operationId: listCharacters
      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 characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharacterList'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
components:
  schemas:
    CharacterList:
      type: object
      properties:
        characters:
          type: array
          items:
            $ref: '#/components/schemas/CharacterListItem'
        total:
          type: integer
          description: Total number of characters returned
    CharacterListItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - ready
            - failed
        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

````