Retrieve conversation history

After a session ends, you may need to answer questions such as:

What did the user and agent say?
When did the session start and stop?
Which turn was slow or incomplete?

Conversational AI Engine provides separate retrieval paths for pushed history, pulled history, and turn analytics. Choose the one that matches your needs.

Choose the retrieval method

Goal	Best source	Use this
Receive history automatically when the session ends	Webhook event	`103 agent history`
Receive post-session turn data automatically	Webhook event	`112 turns finished`
Pull the agent's stored memory from your backend workflow	REST API	`Retrieve agent history`
Analyze start, end, and latency for each turn	REST API	`Query conversation turn information`

Use the history webhook for automatic delivery

The 103 agent history webhook event is the best fit when you want the platform to push session history to your server after the agent stops.

This event includes:

agent_id
name
channel
start_ts
stop_ts
contents
labels

Each contents item includes the message sender and content, which is enough for common transcript-style archiving and post-session review.

For sessions that use llm.vendor set to custom, each contents item can also include speech timing fields:

speech_start_ms: Unix timestamp in milliseconds indicating when the user started speaking or the agent started TTS playback.
speech_end_ms: Unix timestamp in milliseconds indicating when the user stopped speaking, or when TTS playback completed or was interrupted.
speech_algorithmic_delay: Total delay in milliseconds introduced by audio processing algorithms after audio is captured from the user's microphone. This field is returned only when contents[].role is user and actual voice input is present.

Use these timing fields when you need to align transcript entries with cloud recording audio or analyze the actual speech timeline.

Use `112 turns finished` for pushed turn analytics

112 turns finished is the best fit when you want Agora to push conversation turn data after the session ends.

This event includes turn start and end metadata, latency metrics, total_turn_count, and is_truncated, which help with post-session analysis and archiving.

Use the history API when you need to pull data

Use Retrieve agent history when:

Your backend needs to fetch history on demand
You need a pull-based workflow instead of webhook delivery
The session is still running and you want the current stored memory

This path is often better for internal tools and admin workflows where users open a session record and fetch the latest stored memory explicitly.

Use the turns API for diagnostics

Use Query conversation turn information when you care about turn lifecycle and timing more than message text.

This API is the better choice for questions such as:

Which turn was slow?
Which turn ended abnormally?
How many turns completed successfully?

If you need both transcript content and timing analysis, store the 103 agent history event and query the turns API for deeper diagnostics.

Set the history limit before you start the agent

The number of stored history items in 103 agent history depends on llm.max_history when you start the agent. The default is 32.

If your sessions are longer, increase that value when creating the agent:

{
  "llm": {
    "max_history": 64
  }
}

Choose a value that matches your retention and payload-size expectations.

Recommended storage pattern

When your server receives history after the session ends:

Store the raw 103 payload for traceability.
Index records by agent_id, channel, and stop_ts.
Preserve labels so you can filter by tenant, campaign, environment, or experiment.
Link the stored history to turn-level analytics from turns when needed.

Common decision rules

Use these rules to quickly choose a retrieval option:

For immediate delivery when the session ends, use 103 agent history.
For pushed turn data after the session ends, use 112 turns finished.
For on-demand fetching, use the history API.
For timing and completion analysis, use the turns API.
For complete postmortems, combine all three.