> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illocution.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Schemas

> Detailed schemas for API responses

## Timeline Entry

Each element under `timeline` contains multimodal signals for a single utterance.

<ResponseField name="utterance_id" type="string">
  Unique identifier for the utterance
</ResponseField>

<ResponseField name="speaker" type="string">
  Speaker identifier from diarization
</ResponseField>

<ResponseField name="t_start" type="number">
  Start time in seconds
</ResponseField>

<ResponseField name="t_end" type="number">
  End time in seconds
</ResponseField>

<ResponseField name="text" type="string">
  Transcribed text from speech recognition
</ResponseField>

<ResponseField name="asr_confidence" type="number">
  ASR confidence score (0-1)
</ResponseField>

<ResponseField name="prosody" type="object">
  Acoustic metrics including:

  * Pitch/energy statistics
  * Pauses
  * Spectral features
  * Commitment/passion markers
  * Lexical markers
  * Hesitation flags
</ResponseField>

<ResponseField name="prosody_desc" type="string">
  Natural-language descriptor (e.g., "COMMITTED, PASSIONATE, emphatic")
</ResponseField>

<ResponseField name="emotion" type="object">
  Full emotion analysis including:

  * Emotion scores (joy, sadness, etc.)
  * PAD scores (valence, arousal, dominance)
  * Dominant emotion
  * Confidence
</ResponseField>

<ResponseField name="sentiment" type="object">
  Structured sentiment analysis
</ResponseField>

<ResponseField name="polarity" type="number">
  Sentiment polarity (-1 to 1)
</ResponseField>

<ResponseField name="subjectivity" type="number">
  Subjectivity score (0-1)
</ResponseField>

<ResponseField name="cognitive" type="object">
  Cognitive analysis including:

  * Engagement score
  * Cognitive load level
  * Cognitive signals
</ResponseField>

<ResponseField name="commitment_score" type="number">
  Derived commitment score from prosody
</ResponseField>

<ResponseField name="commitment_level" type="string">
  Commitment level classification
</ResponseField>

<ResponseField name="passion_score" type="number">
  Derived passion score from prosody
</ResponseField>

<ResponseField name="passion_level" type="string">
  Passion level classification
</ResponseField>

<ResponseField name="conviction_score" type="number">
  Conviction score derived from prosody and acoustic reasoning
</ResponseField>

<ResponseField name="lexical_markers" type="object">
  Lexical analysis including:

  * Hedges
  * Fillers
  * Questions
  * Disfluency rate
  * Self-repair flags
</ResponseField>

<ResponseField name="acoustic_reasoning" type="string">
  Narrative produced explaining how acoustic cues map to cognition/emotion
</ResponseField>

<ResponseField name="confidence" type="number">
  Average confidence across all agents (0-1)
</ResponseField>

## ConversationSummary Schema (Reference)

Fields:

| Field                  | Type                               | Notes                                                      |        |          |                       |
| ---------------------- | ---------------------------------- | ---------------------------------------------------------- | ------ | -------- | --------------------- |
| `overview`             | string                             | Executive-level synopsis.                                  |        |          |                       |
| `key_insights`         | string\[]                          | Bullet-ready highlights (timestamp references encouraged). |        |          |                       |
| `notable_patterns`     | string\[]                          | Trends across the conversation.                            |        |          |                       |
| `recommendations`      | string\[]                          | Actionable next steps.                                     |        |          |                       |
| `what_went_well`       | string\[] \| null                  | Populated when the user explicitly asks "what went well."  |        |          |                       |
| `what_went_wrong`      | string\[] \| null                  | Populated on "what went wrong" requests.                   |        |          |                       |
| `speaker_dynamics`     | `[{speaker, description}]` \| null | Characterization per speaker.                              |        |          |                       |
| `conversation_quality` | \`"excellent"                      | "good"                                                     | "fair" | "poor"\` | Defaults to `"good"`. |

When contexts such as "call out what went well" are provided, those optional arrays will contain 3-5 evidence-backed bullets.

## Insights

Aggregated insights from the fusion service.

<ResponseField name="overall_sentiment" type="object">
  Sentiment statistics:

  * `mean`: Average sentiment score
  * `std`: Standard deviation
  * `trend`: Sentiment trend (increasing/decreasing/stable)
</ResponseField>

<ResponseField name="dominant_emotions" type="array">
  Top three dominant emotions (strings)
</ResponseField>

<ResponseField name="engagement_pattern" type="string">
  Engagement pattern: `increasing`, `decreasing`, or `stable`
</ResponseField>

<ResponseField name="key_moments" type="array">
  Curated subset of detected moments (MomentEvent objects)
</ResponseField>

<ResponseField name="speaker_profiles" type="object">
  Profiles for each speaker
</ResponseField>

<ResponseField name="conversation_dynamics" type="object">
  Analysis of conversation dynamics
</ResponseField>

<ResponseField name="cognitive_profile" type="object">
  Overall cognitive profile
</ResponseField>

## Transition Event

Affective state transition detection.

<ResponseField name="transition_id" type="string">
  Unique transition identifier
</ResponseField>

<ResponseField name="at_ms" type="integer">
  Timestamp in milliseconds
</ResponseField>

<ResponseField name="from_state" type="object">
  Previous affective state
</ResponseField>

<ResponseField name="to_state" type="object">
  New affective state
</ResponseField>

<ResponseField name="evidence_utterance_ids" type="array">
  Array of utterance IDs that contributed to this transition
</ResponseField>

<ResponseField name="drivers" type="object">
  Valence/arousal/engagement deltas that triggered the transition
</ResponseField>

<ResponseField name="confidence" type="number">
  Confidence score (0-1)
</ResponseField>

<ResponseField name="stability" type="string">
  Stability indicator
</ResponseField>

## Moment Event

Key moment detection.

<ResponseField name="moment_id" type="string">
  Unique moment identifier
</ResponseField>

<ResponseField name="category" type="string">
  Moment category: `objection`, `cta_offered`, `cta_accepted`, `cta_rejected`, `topic_shift`
</ResponseField>

<ResponseField name="speaker_id" type="string">
  Speaker identifier
</ResponseField>

<ResponseField name="start_ms" type="integer">
  Start timestamp in milliseconds
</ResponseField>

<ResponseField name="end_ms" type="integer">
  End timestamp in milliseconds
</ResponseField>

<ResponseField name="utterance_ids" type="array">
  Array of associated utterance IDs
</ResponseField>

<ResponseField name="summary" type="string">
  Summary of the moment
</ResponseField>

<ResponseField name="labels" type="array">
  Additional labels
</ResponseField>

<ResponseField name="confidence" type="number">
  Confidence score (0-1)
</ResponseField>

## Conversation Segmentation

Segmentation of conversation into phases.

<ResponseField name="phases" type="array">
  Array of ConversationPhase objects
</ResponseField>

<ResponseField name="total_phases" type="integer">
  Total number of phases
</ResponseField>

<ResponseField name="segmentation_rationale" type="string">
  Explanation of segmentation approach
</ResponseField>

<ResponseField name="narrative_arc" type="string" optional>
  Narrative arc description
</ResponseField>

<ResponseField name="key_transitions" type="array" optional>
  Array of key transitions (TransitionEvent objects)
</ResponseField>

## Conversation Phase

Individual phase within a segmented conversation.

<ResponseField name="phase_id" type="string">
  Unique phase identifier
</ResponseField>

<ResponseField name="phase_name" type="string">
  Name of the phase
</ResponseField>

<ResponseField name="start_timestamp" type="number">
  Start timestamp in seconds
</ResponseField>

<ResponseField name="end_timestamp" type="number">
  End timestamp in seconds
</ResponseField>

<ResponseField name="start_utterance_id" type="string">
  First utterance ID in this phase
</ResponseField>

<ResponseField name="end_utterance_id" type="string">
  Last utterance ID in this phase
</ResponseField>

<ResponseField name="utterance_count" type="integer">
  Number of utterances in this phase
</ResponseField>

<ResponseField name="theme" type="string">
  Theme of the phase
</ResponseField>

<ResponseField name="summary" type="string">
  Summary of the phase
</ResponseField>

<ResponseField name="emotional_tone" type="string">
  Emotional tone of the phase
</ResponseField>

<ResponseField name="key_moments" type="array">
  Key moments within this phase (MomentEvent objects)
</ResponseField>

<ResponseField name="transition_signal" type="object" optional>
  Transition signal that led to this phase (TransitionEvent)
</ResponseField>

## Error Response

Standard error response format.

<ResponseField name="detail" type="string">
  Error message describing what went wrong
</ResponseField>

**Example:**

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

## Live Session Response

Response from starting a live session.

<ResponseField name="session_id" type="string">
  Unique session identifier
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 timestamp when session expires
</ResponseField>

<ResponseField name="status" type="string">
  Current session status
</ResponseField>

<ResponseField name="next_chunk_seq" type="integer">
  Next expected chunk sequence number (zero-based)
</ResponseField>

## Metrics Response

Observability metrics for dashboards.

<ResponseField name="events" type="object">
  Event counts by type:

  * `status`: Number of status events
  * `final_transcript`: Number of final transcript events
  * `emotion`: Number of emotion events
  * Additional event types as key-value pairs
</ResponseField>

<ResponseField name="agent_latency_ms" type="object">
  Average agent latency per utterance type (milliseconds)
</ResponseField>

**Example:**

```json theme={null}
{
  "events": {
    "status": 45,
    "final_transcript": 12,
    "emotion": 12
  },
  "agent_latency_ms": {
    "utterance": 215.34
  }
}
```