# Call Trace Analysis

The call trace analysis endpoints provide deep understanding of individual calls, including emotional dynamics, decision quality, coaching recommendations, and interaction patterns.

## Endpoints

| Method | Path                              | Description                                          |
| ------ | --------------------------------- | ---------------------------------------------------- |
| GET    | `/calls/traces`                   | List call trace analyses with filters and pagination |
| GET    | `/calls/{call_id}/trace-analysis` | Get detailed trace analysis for a specific call      |

## List Trace Analyses

`GET /calls/traces`

Returns a paginated list of call trace analyses.

### Query Parameters

| Parameter            | Type     | Default | Description                                                        |
| -------------------- | -------- | ------- | ------------------------------------------------------------------ |
| `outcome`            | string   | -       | Filter by outcome: `succeeded`, `partially`, `failed`, `abandoned` |
| `min_computed_at`    | datetime | -       | Only include analyses computed after this timestamp                |
| `max_computed_at`    | datetime | -       | Only include analyses computed before this timestamp               |
| `limit`              | integer  | 20      | Max results per page (1-100)                                       |
| `continuation_token` | integer  | -       | Offset for the next page of results                                |

### Response

| Field                | Type    | Description                        |
| -------------------- | ------- | ---------------------------------- |
| `items`              | array   | List of trace analysis summaries   |
| `has_more`           | boolean | Whether more results are available |
| `continuation_token` | integer | Token to pass for the next page    |

Each item in `items`:

| Field              | Type     | Description                               |
| ------------------ | -------- | ----------------------------------------- |
| `call_sid`         | string   | Call identifier                           |
| `call_entity_id`   | string   | Associated entity ID                      |
| `summary`          | string   | Brief narrative summary of the call       |
| `outcome`          | string   | Call outcome classification               |
| `emotional_arc`    | string   | High-level emotional trajectory           |
| `key_moment_count` | integer  | Number of key decision moments identified |
| `computed_at`      | datetime | When the analysis was computed            |

## Get Trace Analysis

`GET /calls/{call_id}/trace-analysis`

Returns the full trace analysis for a specific call.

### Path Parameters

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| `call_id` | string | Call SID or call entity ID |

### Response

| Field                       | Type             | Description                                                             |
| --------------------------- | ---------------- | ----------------------------------------------------------------------- |
| `call_sid`                  | string           | Call identifier                                                         |
| `call_entity_id`            | string           | Associated entity ID                                                    |
| `status`                    | string           | Analysis status: `ready`, `pending`, or `unavailable`                   |
| `summary`                   | string           | Narrative summary of the call                                           |
| `outcome`                   | string           | Outcome classification: `succeeded`, `partially`, `failed`, `abandoned` |
| `emotional_arc`             | string           | High-level emotional trajectory across the call                         |
| `key_moment_count`          | integer          | Number of key decision moments                                          |
| `computed_at`               | datetime         | When the analysis was computed                                          |
| `key_moments`               | array            | Key decision points (see below)                                         |
| `coaching`                  | array            | Coaching recommendations (see below)                                    |
| `counterfactuals`           | array            | Alternative actions (see below)                                         |
| `emotional_shifts`          | array            | Emotional state changes (see below)                                     |
| `signal_response_alignment` | array            | Signal-response alignment assessments (see below)                       |
| `interaction_dynamics`      | object           | System-level conversation analysis (see below)                          |
| `missed_opportunities`      | array of strings | Patterns the agent could have acted on                                  |
| `emergent_patterns`         | array of strings | Behavioral patterns detected                                            |
| `deep_understanding`        | string           | Synthesized understanding of the conversation                           |

### Key Moment

| Field               | Type   | Description                                                                             |
| ------------------- | ------ | --------------------------------------------------------------------------------------- |
| `what_happened`     | string | Description of the decision point                                                       |
| `timestamp_seconds` | number | Position in the call (seconds)                                                          |
| `quality`           | string | Quality assessment: `optimal`, `adequate`, `suboptimal`                                 |
| `reasoning`         | string | Why the agent made this decision                                                        |
| `alternative`       | string | What the agent could have done instead                                                  |
| `decision_factors`  | array  | Factors that drove the decision, each with `factor` (string) and `source_type` (string) |

### Coaching Item

| Field              | Type   | Description                            |
| ------------------ | ------ | -------------------------------------- |
| `observation`      | string | What was observed in the call          |
| `recommendation`   | string | Suggested improvement                  |
| `moment_timestamp` | number | Position in the call (seconds)         |
| `expected_impact`  | string | Predicted effect of the recommendation |

### Counterfactual

| Field               | Type   | Description                        |
| ------------------- | ------ | ---------------------------------- |
| `actual`            | string | What actually happened             |
| `alternative`       | string | What could have happened instead   |
| `predicted_impact`  | string | Expected effect of the alternative |
| `timestamp_seconds` | number | Position in the call (seconds)     |

### Emotional Shift

| Field               | Type   | Description                            |
| ------------------- | ------ | -------------------------------------- |
| `from_state`        | string | Emotional state before the shift       |
| `to_state`          | string | Emotional state after the shift        |
| `trigger`           | string | What caused the shift                  |
| `agent_awareness`   | string | Whether the agent recognized the shift |
| `timestamp_seconds` | number | Position in the call (seconds)         |

### Signal-Response Alignment

| Field            | Type   | Description                                    |
| ---------------- | ------ | ---------------------------------------------- |
| `signal`         | string | The salient signal from the caller             |
| `agent_response` | string | How the agent responded                        |
| `alignment`      | string | Assessment: `aligned`, `misaligned`, `partial` |
| `insight`        | string | Additional context about the alignment         |

### Interaction Dynamics

| Field                  | Type   | Description                                     |
| ---------------------- | ------ | ----------------------------------------------- |
| `turn_taking_quality`  | string | Assessment of conversational turn-taking        |
| `information_density`  | string | How efficiently information was exchanged       |
| `rapport_trajectory`   | string | How rapport evolved during the call             |
| `repair_effectiveness` | string | How well communication breakdowns were resolved |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/platform-api/call-trace-analysis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.