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

# List Cast Members

> Retrieve all cast member assignments

## Overview

Returns a list of all cast member assignments linking people to productions. Includes nested data for the person, production, and role. Optionally filter by person ID.

## Query Parameters

<ParamField query="person_id" type="string">
  Filter cast members by person ID to see all their roles
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  # Get all cast members
  curl https://entertheatre.com/api/cast-members

  # Filter by person
  curl https://entertheatre.com/api/cast-members?person_id=person-001
  ```

  ```javascript JavaScript theme={null}
  // Get all cast members
  const response = await fetch('https://entertheatre.com/api/cast-members');
  const castMembers = await response.json();

  // Filter by person
  const filtered = await fetch('https://entertheatre.com/api/cast-members?person_id=person-001');
  const personRoles = await filtered.json();
  ```

  ```python Python theme={null}
  import requests

  # Get all cast members
  response = requests.get('https://entertheatre.com/api/cast-members')
  cast_members = response.json()

  # Filter by person
  response = requests.get('https://entertheatre.com/api/cast-members', params={'person_id': 'person-001'})
  person_roles = response.json()
  ```
</CodeGroup>

## Response

<ResponseField name="cast_members" type="array">
  Array of cast member objects

  <Expandable title="Cast Member Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the cast member assignment
    </ResponseField>

    <ResponseField name="person_id" type="string" required>
      ID of the person
    </ResponseField>

    <ResponseField name="production_id" type="string" required>
      ID of the production
    </ResponseField>

    <ResponseField name="role_id" type="string">
      ID of the role/character (if applicable)
    </ResponseField>

    <ResponseField name="role_type" type="string" required>
      Type of role: `principal`, `ensemble`, `understudy`, `swing`, `standby`, `alternate`
    </ResponseField>

    <ResponseField name="billing_order" type="number">
      Order in the billing (1 = top billing)
    </ResponseField>

    <ResponseField name="person" type="object">
      Nested person object with name, bio, and image
    </ResponseField>

    <ResponseField name="production" type="object">
      Nested production object with show details
    </ResponseField>

    <ResponseField name="role" type="object">
      Nested role object with character name
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
[
  {
    "id": "cast-001",
    "person_id": "person-001",
    "production_id": "prod-001",
    "role_id": "role-001",
    "role_type": "principal",
    "billing_order": 1,
    "person": {
      "id": "person-001",
      "name": "Elaine Paige",
      "bio": "Legendary West End star...",
      "image": "https://example.com/elaine.jpg"
    },
    "production": {
      "id": "prod-001",
      "show": {
        "name": "Cats",
        "type": "musical"
      }
    },
    "role": {
      "id": "role-001",
      "name": "Grizabella"
    }
  },
  {
    "id": "cast-002",
    "person_id": "person-002",
    "production_id": "prod-002",
    "role_id": "role-005",
    "role_type": "principal",
    "billing_order": 1,
    "person": {
      "id": "person-002",
      "name": "Michael Ball",
      "bio": "Award-winning musical theatre actor...",
      "image": "https://example.com/michael.jpg"
    },
    "production": {
      "id": "prod-002",
      "show": {
        "name": "Les Miserables",
        "type": "musical"
      }
    },
    "role": {
      "id": "role-005",
      "name": "Marius"
    }
  }
]
```

## Status Codes

| Status | Description                             |
| ------ | --------------------------------------- |
| `200`  | Success - returns array of cast members |
| `500`  | Server error                            |