> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.formantai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.formantai.com/_mcp/server.

# Conversations

> Retrieve call history, transcripts, structured results, and recordings.

Conversation endpoints expose the result of completed and attempted calls.

## List conversations

```http
GET /v1/conversations
```

```bash
curl "https://api.voice.formantai.com/v1/conversations?agent_id=123&limit=20&offset=0" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

| Query parameter | Type    | Description                  |
| --------------- | ------- | ---------------------------- |
| `agent_id`      | integer | Optional filter by agent.    |
| `limit`         | integer | Default `20`, maximum `100`. |
| `offset`        | integer | Pagination offset.           |

```json
{
  "data": [
    {
      "agent_id": 123,
      "contact_number": "+919876543210",
      "conversation_id": "e36853de-9cbb-441e-ad75-d3c8ac82abfb_1",
      "duration_seconds": 142,
      "end_timestamp": 1773867341766,
      "start_timestamp": 1773867201766,
      "status": "completed"
    }
  ],
  "has_more": false,
  "total": 1
}
```

## Get one conversation

```http
GET /v1/conversations/{conversation_id}
```

```bash
curl "https://api.voice.formantai.com/v1/conversations/e36853de-9cbb-441e-ad75-d3c8ac82abfb_1" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

The response includes transcript and results when available.

```json
{
  "data": {
    "agent_id": 123,
    "contact_number": "+919876543210",
    "conversation_id": "e36853de-9cbb-441e-ad75-d3c8ac82abfb_1",
    "duration_seconds": 142,
    "failure_reason": null,
    "results": {
      "intent": "payment_confirmed",
      "sentiment": "positive"
    },
    "status": "completed",
    "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transcript": [
      { "role": "agent", "message": "Hello Rahul..." },
      { "role": "human", "message": "Yes, I can talk." }
    ]
  }
}
```

## Download recording

```http
GET /v1/conversations/{conversation_id}/recording
```

```bash
curl "https://api.voice.formantai.com/v1/conversations/e36853de-9cbb-441e-ad75-d3c8ac82abfb_1/recording" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  --output recording.wav
```

Recordings may not be available immediately for every call. A missing recording returns a `not_found` error.

## Status values

Common statuses include:

| Status             | Meaning                                     |
| ------------------ | ------------------------------------------- |
| `completed`        | Call connected and ended normally.          |
| `failed`           | Call setup or provider interaction failed.  |
| `busy`             | Recipient was busy.                         |
| `no_answer`        | Recipient did not answer.                   |
| `socket_failure`   | Call connected but voice streaming failed.  |
| `telephony_failed` | Telephony provider failed after initiation. |
| `unreachable`      | Destination number could not be reached.    |