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

# List Roleplay Training Calls — Shilo API

> Retrieve a paginated list of AI roleplay training calls. Filter by user, contact, stage, or source. Each roleplay includes scenario metadata and is separate from live call recordings.

Use this endpoint to retrieve a paginated list of roleplay training calls from your Shilo account. Roleplays are practice sessions where your agents interact with AI-simulated leads to sharpen their sales skills. You can filter results by user, contact, scenario stage, or source, and navigate large result sets with cursor-based pagination. Roleplays are returned separately from standard call recordings — use the `/api/v1/calls` endpoint for non-roleplay recordings.

## Endpoint

```
GET https://api.shilo.ai/api/v1/roleplays
```

## Authentication

All requests require your API key in the `x-api-key` header.

## Query Parameters

<ParamField query="limit" type="number" default="50">
  The maximum number of roleplay records to return per page. Accepted values are between `1` and `100`.
</ParamField>

<ParamField query="cursor" type="string">
  An opaque pagination cursor returned in the previous response's `pagination.next_cursor` field. Pass this value to retrieve the next page of results. Omit to start from the beginning.
</ParamField>

<ParamField query="sort" type="string" default="asc">
  The sort order for results, based on `created_date`. Accepted values are `asc` (oldest first) or `desc` (newest first).
</ParamField>

<ParamField query="created_date_gte" type="string">
  Return only roleplays created on or after this date and time. Must be an ISO-8601 formatted string (e.g., `2030-01-01T00:00:00Z`).
</ParamField>

<ParamField query="created_date_lte" type="string">
  Return only roleplays created on or before this date and time. Must be an ISO-8601 formatted string (e.g., `2030-12-31T23:59:59Z`).
</ParamField>

<ParamField query="source_id" type="string">
  Filter roleplays by the source they were generated from.
</ParamField>

<ParamField query="user_id" type="string">
  Filter roleplays by the associated agent. Accepts a prefix-qualified identifier in one of three formats:

  * `id:{uuid}` — Shilo user UUID
  * `external_user_id:{value}` — your external user ID
  * `{uuid}` — bare Shilo user UUID (shorthand)
</ParamField>

<ParamField query="contact_id" type="string">
  Filter roleplays by the associated contact. Accepts a prefix-qualified identifier in one of three formats:

  * `id:{uuid}` — Shilo contact UUID
  * `external_contact_id:{value}` — your external contact ID
  * `{uuid}` — bare Shilo contact UUID (shorthand)
</ParamField>

<ParamField query="stage_id" type="string">
  Filter roleplays by the pipeline stage associated with the scenario (e.g., prospecting, discovery, closing).
</ParamField>

## Response

A successful request returns HTTP `200` with a `RoleplaysResponseDto` object.

<ResponseField name="data" type="Roleplay[]">
  An array of Roleplay objects matching the query filters.

  <Expandable title="Roleplay fields">
    <ResponseField name="id" type="string" required>
      The Shilo UUID for this roleplay record.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Always `"roleplay"` for records returned by this endpoint.
    </ResponseField>

    <ResponseField name="created_date" type="string" required>
      The ISO-8601 timestamp indicating when this roleplay was created in Shilo.
    </ResponseField>

    <ResponseField name="duration" type="number | null">
      The duration of the roleplay call in seconds. `null` if not yet available.
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      The Shilo UUID of the agent who completed this roleplay. `null` if no user is matched.
    </ResponseField>

    <ResponseField name="external_user_id" type="string | null">
      The external user ID for the agent, as provided by your integration. `null` if not provided.
    </ResponseField>

    <ResponseField name="contact_id" type="string | null">
      The Shilo UUID of the contact associated with this roleplay. `null` if no contact is matched.
    </ResponseField>

    <ResponseField name="external_contact_id" type="string | null">
      The external contact ID for the associated contact, as provided by your integration. `null` if not provided.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Metadata for paginating through additional results.

  <Expandable title="Pagination fields">
    <ResponseField name="has_more" type="boolean" required>
      `true` if there are additional pages of results beyond the current response; `false` if this is the last page.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      An opaque cursor string to pass as the `cursor` query parameter in your next request. Returns `null` when there are no further pages.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Roleplays are returned separately from regular call recordings. Use the `/api/v1/calls` endpoint to list non-roleplay call recordings.
</Note>

### Error Responses

| Status             | Description                            |
| ------------------ | -------------------------------------- |
| `401 Unauthorized` | Missing or invalid `x-api-key` header. |

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/roleplays?limit=50&sort=desc" \
  --header "x-api-key: YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "type": "roleplay",
      "created_date": "2030-09-24T12:34:56Z",
      "duration": 300,
      "external_user_id": "agent-1",
      "user_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "contact_id": null,
      "external_contact_id": null
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```