Retrieve Roleplay Analysis — Shilo API

Use this endpoint to retrieve the AI-generated analysis for a roleplay training call. After each roleplay session, Shilo processes the recording asynchronously to produce detailed coaching feedback, a performance rating, objection and disposition analysis, speaker identification, and a session summary. Because processing takes time, you should poll this endpoint and check the progress field — all result fields are only fully populated once progress reaches 100.

Endpoint

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

Authentication

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

Path Parameters

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)

Response

A successful request returns HTTP 200 with a RecordingAnalysis object. The top-level fields id, recording_id, created_at, and progress are always present. All sub-resource fields (coaching, rating, summary, etc.) are optional and only fully populated once progress equals 100.

string

required

The UUID of this analysis record.

string

required

The Shilo UUID of the roleplay this analysis belongs to.

string

required

The ISO-8601 timestamp indicating when this analysis was created.

number

required

A value between 0 and 100 representing how far along the AI processing pipeline this roleplay is. Poll this endpoint until progress equals 100 before reading any result fields.

object

Recommended follow-up actions identified by the AI. Present only after processing completes.

Show action_items fields

string

The UUID of this action items record.

string[]

The most important practice or follow-up actions for the agent.

string[]

Additional, lower-priority practice actions.

object

AI-generated coaching feedback for the agent on this roleplay session. Present only after processing completes.

Show coaching fields

string

The UUID of this coaching record.

string[]

Areas where the agent could improve, with specific, actionable suggestions.

string[]

Highlights from the session where the agent performed particularly well.

object

The AI-assessed outcome and reasoning for this roleplay session. Present only after processing completes.

Show disposition fields

string

The UUID of this disposition record.

string[]

The determined outcome labels for the session (e.g., appointment set, not interested).

string

A plain-language explanation of why the AI assigned these outcomes.

object

Objections raised by the AI-simulated lead during the roleplay. Present only after processing completes.

Show objections fields

string

The UUID of this objections record.

string[]

A list of objections identified in the conversation.

object

A numeric quality rating assigned to the agent’s performance on this roleplay. Present only after processing completes.

Show rating fields

string

The UUID of this rating record.

number

The numeric rating score assigned to the agent’s performance.

string

A plain-language explanation of what drove the assigned score.

object

AI-resolved speaker identities for the roleplay recording. Present only after processing completes.

Show speakers fields

string

The UUID of this speakers record.

string

The resolved name of the agent in this recording.

string

The resolved name of the AI-simulated lead in this recording.

object

A concise AI-generated summary of the roleplay session. Present only after processing completes.

Show summary fields

string

The UUID of this summary record.

object

An object containing the summary text.

Show outcome fields

string

The full text of the AI-generated roleplay session summary.

Poll this endpoint until progress equals 100 before reading result fields such as coaching, rating, or summary. Sub-resource fields are absent or incomplete until processing finishes.

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

curl --request GET \
  --url "https://api.shilo.ai/api/v1/roleplays/ee6f2136-b94a-4438-9335-3acf5b2a0d31/analysis" \
  --header "x-api-key: YOUR_API_KEY"

Example Response

{
  "id": "b2c3d4e5-0000-4000-8000-111122223333",
  "recording_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "created_at": "2030-09-24T12:40:00Z",
  "progress": 100,
  "action_items": {
    "id": "b2c3d4e5-0000-4000-8000-aaaaaaaaaaaa",
    "primary": [
      "Practice transitioning from discovery to pitch more smoothly",
      "Review objection-handling scripts for price resistance"
    ],
    "secondary": [
      "Work on pacing — slow down during value proposition delivery"
    ]
  },
  "coaching": {
    "id": "b2c3d4e5-0000-4000-8000-bbbbbbbbbbbb",
    "possible_improvements": [
      "Ask more clarifying questions before presenting the offer",
      "Avoid interrupting the lead during objection statements"
    ],
    "top_moments": [
      "Strong opening hook that captured interest immediately",
      "Effective use of social proof when handling the trust objection"
    ]
  },
  "disposition": {
    "id": "b2c3d4e5-0000-4000-8000-cccccccccccc",
    "outcomes": ["appointment_set"],
    "reasoning": "The agent successfully navigated the lead's hesitation and secured a commitment for a follow-up meeting."
  },
  "objections": {
    "id": "b2c3d4e5-0000-4000-8000-dddddddddddd",
    "outcomes": [
      "Not the right time",
      "Already working with a competitor"
    ]
  },
  "rating": {
    "id": "b2c3d4e5-0000-4000-8000-eeeeeeeeeeee",
    "outcome": 76,
    "reasoning": "The agent showed strong closing instincts but needs to develop more deliberate discovery questioning before moving to the pitch."
  },
  "speakers": {
    "id": "b2c3d4e5-0000-4000-8000-ffffffffffff",
    "user_name": "Taylor Morgan",
    "client_name": "AI Lead"
  },
  "summary": {
    "id": "b2c3d4e5-0000-4000-8000-000000000000",
    "outcome": {
      "summary": "Taylor practiced a cold outreach scenario against an AI-simulated lead who raised timing and competitive objections. Taylor overcame both and secured a mock appointment, though the session highlighted an opportunity to invest more time in early-stage discovery before transitioning to the pitch."
    }
  }
}

Overview

Calls

Appointments

Roleplays

Contacts

Users

Invitations

Metrics

Coaching

Retrieve Roleplay Analysis — Shilo API

Endpoint

Authentication

Path Parameters

Response

Error Responses

Example Request

Example Response

​Endpoint

​Authentication

​Path Parameters

​Response

​Error Responses

​Example Request

​Example Response

Endpoint

Authentication

Path Parameters

Response

Error Responses

Example Request

Example Response