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

# Retrieve a Roleplay Training Call — Shilo API

> Retrieve a single processed roleplay call by its Shilo UUID or call event ID. Returns the Roleplay object with scenario metadata, user, contact, and recording details.

Use this endpoint to fetch a single roleplay training call by its identifier. You can look up a roleplay using either the Shilo-generated UUID or the call event ID associated with the session. This is useful for confirming that a roleplay has been processed or for retrieving its metadata before fetching analysis or transcript data.

## Endpoint

```
GET https://api.shilo.ai/api/v1/roleplays/{identifier}
```

## Authentication

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

## Path Parameters

<ParamField path="identifier" type="string" required>
  The unique identifier for the roleplay. Two formats are accepted:

  * `{uuid}` — The Shilo roleplay UUID (e.g., `ee6f2136-b94a-4438-9335-3acf5b2a0d31`)
  * `call_event_id:{uuid}` — The Shilo Call Event UUID associated with this roleplay session (e.g., `call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31`)
</ParamField>

## Response

A successful request returns HTTP `200` with the matching Roleplay object.

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

### Error Responses

| Status            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `400 Bad Request` | The `identifier` path parameter is malformed or uses an unsupported format. |
| `404 Not Found`   | No roleplay was found matching the provided identifier.                     |

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/roleplays/ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  --header "x-api-key: YOUR_API_KEY"
```

By call event ID:

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/roleplays/call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  --header "x-api-key: YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "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
}
```