> ## 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 Roleplay Analysis — Shilo API

> Retrieve AI analysis for a roleplay training call including coaching feedback, performance rating, disposition, objections, and session summary. Poll progress until it reaches 100.

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

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

<ResponseField name="id" type="string" required>
  The UUID of this analysis record.
</ResponseField>

<ResponseField name="recording_id" type="string" required>
  The Shilo UUID of the roleplay this analysis belongs to.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  The ISO-8601 timestamp indicating when this analysis was created.
</ResponseField>

<ResponseField name="progress" type="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.
</ResponseField>

<ResponseField name="action_items" type="object">
  Recommended follow-up actions identified by the AI. Present only after processing completes.

  <Expandable title="action_items fields">
    <ResponseField name="id" type="string">
      The UUID of this action items record.
    </ResponseField>

    <ResponseField name="primary" type="string[]">
      The most important practice or follow-up actions for the agent.
    </ResponseField>

    <ResponseField name="secondary" type="string[]">
      Additional, lower-priority practice actions.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="coaching" type="object">
  AI-generated coaching feedback for the agent on this roleplay session. Present only after processing completes.

  <Expandable title="coaching fields">
    <ResponseField name="id" type="string">
      The UUID of this coaching record.
    </ResponseField>

    <ResponseField name="possible_improvements" type="string[]">
      Areas where the agent could improve, with specific, actionable suggestions.
    </ResponseField>

    <ResponseField name="top_moments" type="string[]">
      Highlights from the session where the agent performed particularly well.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="disposition" type="object">
  The AI-assessed outcome and reasoning for this roleplay session. Present only after processing completes.

  <Expandable title="disposition fields">
    <ResponseField name="id" type="string">
      The UUID of this disposition record.
    </ResponseField>

    <ResponseField name="outcomes" type="string[]">
      The determined outcome labels for the session (e.g., appointment set, not interested).
    </ResponseField>

    <ResponseField name="reasoning" type="string">
      A plain-language explanation of why the AI assigned these outcomes.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="objections" type="object">
  Objections raised by the AI-simulated lead during the roleplay. Present only after processing completes.

  <Expandable title="objections fields">
    <ResponseField name="id" type="string">
      The UUID of this objections record.
    </ResponseField>

    <ResponseField name="outcomes" type="string[]">
      A list of objections identified in the conversation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rating" type="object">
  A numeric quality rating assigned to the agent's performance on this roleplay. Present only after processing completes.

  <Expandable title="rating fields">
    <ResponseField name="id" type="string">
      The UUID of this rating record.
    </ResponseField>

    <ResponseField name="outcome" type="number">
      The numeric rating score assigned to the agent's performance.
    </ResponseField>

    <ResponseField name="reasoning" type="string">
      A plain-language explanation of what drove the assigned score.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="speakers" type="object">
  AI-resolved speaker identities for the roleplay recording. Present only after processing completes.

  <Expandable title="speakers fields">
    <ResponseField name="id" type="string">
      The UUID of this speakers record.
    </ResponseField>

    <ResponseField name="user_name" type="string">
      The resolved name of the agent in this recording.
    </ResponseField>

    <ResponseField name="client_name" type="string">
      The resolved name of the AI-simulated lead in this recording.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  A concise AI-generated summary of the roleplay session. Present only after processing completes.

  <Expandable title="summary fields">
    <ResponseField name="id" type="string">
      The UUID of this summary record.
    </ResponseField>

    <ResponseField name="outcome" type="object">
      An object containing the summary text.

      <Expandable title="outcome fields">
        <ResponseField name="summary" type="string">
          The full text of the AI-generated roleplay session summary.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  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.
</Note>

### 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/analysis" \
  --header "x-api-key: YOUR_API_KEY"
```

## Example Response

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