---
title: Retrieve agent history
description: 'Get the history of the conversation between the user and the agent.

  '
sidebar_position: 9
platform: android
exported_from: https://docs.agora.io/en/conversational-ai/rest-api/agent/history
exported_on: '2026-06-11T15:04:03.126608Z'
exported_file: history.md
---

> For a complete site index fetch https://docs.agora.io/llms.txt. For all pages in this product fetch https://docs.agora.io/en/conversational-ai/overview/product-overview.md

[HTML Version](https://docs.agora.io/en/conversational-ai/rest-api/agent/history)

# Retrieve agent history


**Method:** GET
**Endpoint:** `https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/history`

Call this endpoint while the agent is running to retrieve the conversation history between the user and the Conversational AI agent.

## Request

### Path parameters

- **appid** (string, required): The App ID of the project.
- **agentId** (string, required): The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/join.md).

## Response

- If the returned status code is `200`, the request was successful. The response body contains the result of the request.

  **OK**

- **agent_id** (string, optional): Unique identifier of the agent.
- **start_ts** (integer, optional): Agent creation timestamp.
- **status** (string, optional, possible values: `RUNNING`): Agent status. Only supports querying the running agent.
- **contents** (array, optional): Agent history.
  - **role** (string, optional, possible values: `user`, `assistant`): The message sender.
        - `user`: User
        - `assistant`: AI agent
  - **content** (string, optional): Message content.
  - **speech_start_ms** (integer, optional): Unix timestamp in milliseconds indicating when the user started speaking or the agent started TTS playback. Only returned when `llm.vendor` is `custom`.
  - **speech_end_ms** (integer, optional): Unix timestamp in milliseconds indicating when the user stopped speaking, or when TTS playback completed or was interrupted. Only returned when `llm.vendor` is `custom`.
  - **speech_algorithmic_delay** (integer, optional): The total delay in milliseconds introduced by audio processing algorithms, including noise reduction, background voice suppression, and voiceprint locking, after audio is captured from the user's microphone. Use this value to align timestamps with cloud recording audio.
 
        Only returned when:
        - `llm.vendor` is `custom`
        - `contents[].role` is `user`
        - Actual voice input is present

- If the returned status code is not `200`, the request failed. The response body includes the error code and description. Refer to [status codes](https://docs-md.agora.io/en/conversational-ai/rest-api/reference.md) to understand the possible reasons for failure.

## Authorization

This endpoint requires [authentication](https://docs-md.agora.io/en/conversational-ai/rest-api/restful-authentication.md).

## Request example

**curl**
```bash
      curl --request get \
        --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/history \
        --header 'Authorization: Basic'
```

**Python**
```python
    import requests

    url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/history"

    headers = {"Authorization": "Basic"}

    response = requests.request("get", url, headers=headers)

    print(response.text)
```

**Node.js**
```js
    const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/history';
    const options = {method: 'get', headers: {Authorization: 'Basic'}};

    fetch(url, options)
      .then(res => res.json())
      .then(json => console.log(json))
      .catch(err => console.error(err));
```

## Response example

**Default**
```json
  {
    "agent_id": "xxxx",
    "start_ts": 123,
    "status": "RUNNING",
    "contents": [
      {
        "role": "user",
        "content": "hello."
      },
      {
        "role": "assistant",
        "content": "hi, how can I help you?"
      }
    ]
  }
```

**llm.vendor='custom'**
```json
  {
    "agent_id": "xxxx",
    "start_ts": 1715000000,
    "status": "RUNNING",
    "contents": [
      {
        "role": "assistant",
        "content": "Hello, welcome to the AI customer service. How can I help you?",
        "speech_start_ms": 1715000001200,
        "speech_end_ms": 1715000004800
      },
      {
        "role": "user",
        "content": "",
        "speech_start_ms": 1715000004900,
        "speech_end_ms": 1715000005100,
        "speech_algorithmic_delay": 120
      },
      {
        "role": "user",
        "content": "I'd like to check the status of my package, tracking number 12345.",
        "speech_start_ms": 1715000005200,
        "speech_end_ms": 1715000007600,
        "speech_algorithmic_delay": 120
      },
      {
        "role": "assistant",
        "content": "Your package with tracking number 12345 is currently out for delivery.",
        "speech_start_ms": 1715000009500,
        "speech_end_ms": 1715000013200
      },
      {
        "role": "user",
        "content": "[think API injected] User level: VIP"
      }
    ]
  }
```