# Retrieve conversation history (/en/ai/build/handle-runtime-events/retrieve-session-history)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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 [#choose-the-retrieval-method]

| Goal                                                      | Best source   | Use this                                                                                   |
| --------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
| Receive history automatically when the session ends       | Webhook event | [`103 agent history`](../../reference/event-types#103-agent-history)                       |
| Receive post-session turn data automatically              | Webhook event | [`112 turns finished`](../../reference/event-types#112-turns-finished)                     |
| Pull the agent's stored memory from your backend workflow | REST API      | [`Retrieve agent history`](/en/api-reference/api-ref/conversational-ai/history)            |
| Analyze start, end, and latency for each turn             | REST API      | [`Query conversation turn information`](/en/api-reference/api-ref/conversational-ai/turns) |

## Use the history webhook for automatic delivery [#use-the-history-webhook-for-automatic-delivery]

The [`103 agent history`](../../reference/event-types#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 [#use-112-turns-finished-for-pushed-turn-analytics]

[`112 turns finished`](../../reference/event-types#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-the-history-api-when-you-need-to-pull-data]

Use [`Retrieve agent history`](/en/api-reference/api-ref/conversational-ai/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-the-turns-api-for-diagnostics]

Use [`Query conversation turn information`](/en/api-reference/api-ref/conversational-ai/turns) 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 [#set-the-history-limit-before-you-start-the-agent]

The number of stored history items in [`103 agent history`](../../reference/event-types#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:

```json
{
  "llm": {
    "max_history": 64
  }
}
```

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

## Recommended storage pattern [#recommended-storage-pattern]

When your server receives history after the session ends:

1. Store the raw `103` payload for traceability.
2. Index records by `agent_id`, `channel`, and `stop_ts`.
3. Preserve `labels` so you can filter by tenant, campaign, environment, or experiment.
4. Link the stored history to turn-level analytics from [`turns`](/en/api-reference/api-ref/conversational-ai/turns) when needed.

## Common decision rules [#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.

## Related resources [#related-resources]

* [Monitor agent status, errors, and performance](monitor-agent-runtime)
* [Get runtime events](get-runtime-events)
* [Webhooks](webhooks)
* [Notification event types](../../reference/event-types#103-agent-history)
* [Keep conversation context across turns](../shape-the-conversation/short-term-memory)
* [Retrieve agent history](/en/api-reference/api-ref/conversational-ai/history)
* [Query conversation turn information](/en/api-reference/api-ref/conversational-ai/turns)