List Roleplay Training Calls — Shilo API

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

number

default:"50"

The maximum number of roleplay records to return per page. Accepted values are between 1 and 100.

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.

string

default:"asc"

The sort order for results, based on created_date. Accepted values are asc (oldest first) or desc (newest first).

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

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

string

Filter roleplays by the source they were generated from.

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)

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)

string

Filter roleplays by the pipeline stage associated with the scenario (e.g., prospecting, discovery, closing).

Response

A successful request returns HTTP 200 with a RoleplaysResponseDto object.

Roleplay[]

An array of Roleplay objects matching the query filters.

Show Roleplay fields

string

required

The Shilo UUID for this roleplay record.

string

required

Always "roleplay" for records returned by this endpoint.

string

required

The ISO-8601 timestamp indicating when this roleplay was created in Shilo.

number | null

The duration of the roleplay call in seconds. null if not yet available.

string | null

The Shilo UUID of the agent who completed this roleplay. null if no user is matched.

string | null

The external user ID for the agent, as provided by your integration. null if not provided.

string | null

The Shilo UUID of the contact associated with this roleplay. null if no contact is matched.

string | null

The external contact ID for the associated contact, as provided by your integration. null if not provided.

object

required

Metadata for paginating through additional results.

Show Pagination fields

boolean

required

true if there are additional pages of results beyond the current response; false if this is the last page.

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.

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

Error Responses

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

Example Request

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

Example Response

{
  "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
  }
}

Overview

Calls

Appointments

Roleplays

Contacts

Users

Invitations

Metrics

Coaching

List Roleplay Training Calls — Shilo API

Endpoint

Authentication

Query Parameters

Response

Error Responses

Example Request

Example Response

​Endpoint

​Authentication

​Query Parameters

​Response

​Error Responses

​Example Request

​Example Response

Endpoint

Authentication

Query Parameters

Response

Error Responses

Example Request

Example Response