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

# Conversations API

> List conversations and fetch details, transcripts, and recordings

These endpoints let you retrieve, inspect, and delete conversation data for completed calls.

<Note>
  All requests require an `Authorization: Bearer YOUR_GUAVA_API_KEY` header. See the [API Overview](/api-reference/api-overview) for details.
</Note>

## List conversations

```
GET /v1/conversations
```

List your organization's conversations, newest first. Use the filters below to narrow results — for example, to pull every call to or from a given phone number, with each call's duration, to build a usage or billing report.

### Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `from_number` | string | No | Only return calls placed from this number. E.164 format (e.g. `+15551234567`). |
| `to_number` | string | No | Only return calls placed to this number. E.164 format. |
| `direction` | string | No | Only return calls in this direction: `"inbound"` or `"outbound"` (from the perspective of your agent). Use `"all"` or omit for both. |
| `date_from` | string | No | Only return calls at or after this time (ISO 8601, e.g. `2026-06-01T00:00:00Z`). |
| `date_to` | string | No | Only return calls at or before this time (ISO 8601). |
| `campaign_id` | string | No | Only return calls placed by this outbound campaign. |
| `limit` | integer | No | Maximum number of conversations to return, between 1 and 100. Defaults to 50. |
| `after` | string | No | Pagination cursor. Pass the `next_cursor` from the previous response to fetch the next page. |

### Response

A JSON object with the following fields:

| Field | Type | Description |
| - | - | - |
| `conversations` | array | The matching conversations, newest first. Each is the same object returned by [Get conversation details](#get-conversation-details). |
| `next_cursor` | string (nullable) | Pass as `after` to fetch the next page. `null` when there are no more results. |
| `has_more` | boolean | `true` if more conversations match than were returned in this response. |

Each conversation includes the call's `duration_sec`, so you can total call time without fetching each conversation individually.

### Pagination

Conversations are returned newest first. When `has_more` is `true`, request the next page by calling again with `after` set to the `next_cursor` from the previous response. Keep paging until `has_more` is `false` to retrieve the full set.

### Errors

| Status | Description |
| - | - |
| 400 | Invalid `limit`, `after` cursor, `campaign_id`, or date value |
| 401 | Invalid authentication |
| 422 | `from_number` or `to_number` is not a valid E.164 number |

### Example

```bash theme={null}
curl -G https://app.goguava.ai/v1/conversations \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  --data-urlencode 'from_number=+15551234567' \
  --data-urlencode 'date_from=2026-06-01T00:00:00Z'
```

Sample response:

```json theme={null}
{
  "conversations": [
    {
      "id": "6064ab9663dc4eb0",
      "call_id": "6064ab9663dc4eb0",
      "ts": "2026-06-09T00:12:04.518000+00:00",
      "direction": "outbound",
      "from_number": "+15551234567",
      "to_number": "+15551230001",
      "duration_sec": 142,
      "campaign_id": null,
      "termination_reason": "user-hangup"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

<Note>
  The `+` in a phone number must be URL-encoded as `%2B` in query strings. The `curl -G --data-urlencode` form above handles this for you.
</Note>

***

## Get conversation details

```
GET /v1/conversations/{call_id}
```

Retrieve metadata about a single conversation.

### Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `call_id` | string | Yes | ID of the call |

### Response

A JSON object with the following fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique ID of the conversation |
| `call_id` | string | ID of the call |
| `ts` | string | Date of the call in ISO 8601 format |
| `direction` | string | `"inbound"` or `"outbound"` (from the perspective of your agent) |
| `from_number` | string | Phone number that initiated the call |
| `to_number` | string | Phone number that received the call |
| `duration_sec` | integer (nullable) | How long the call lasted in seconds. `null` until the call completes. |
| `campaign_id` | string (nullable) | Outbound campaign that initiated this call, if applicable |
| `termination_reason` | string (nullable) | How the call ended (e.g. `"user-hangup"`), if known |

### Errors

| Status | Description |
| - | - |
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

### Example

```bash theme={null}
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://app.goguava.ai/v1/conversations/6064ab9663dc4eb0
```

***

## Get conversation transcript

```
GET /v1/conversations/{call_id}/transcript
```

Download the transcript for a conversation as a list of turns.

### Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `call_id` | string | Yes | ID of the call |

### Response

A JSON array of turn objects. Each turn has:

| Field | Type | Description |
| - | - | - |
| `speaker` | string | `"HUMAN"` or `"AGENT"` |
| `text` | string | What was said by the speaker |
| `offset_ms` | integer | Milliseconds into the call when this turn began |

### Errors

| Status | Description |
| - | - |
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

### Example

```bash theme={null}
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://app.goguava.ai/v1/conversations/6064ab9663dc4eb0/transcript
```

***

## Get conversation recording

```
GET /v1/conversations/{call_id}/recording
```

Download the audio recording for a conversation in WAV format.

### Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `call_id` | string | Yes | ID of the call |

### Response

WAV audio file.

### Errors

| Status | Description |
| - | - |
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

### Example

```bash theme={null}
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  -o recording.wav \
  https://app.goguava.ai/v1/conversations/6064ab9663dc4eb0/recording
```

***

## Get conversation channel recording

```
GET /v1/conversations/{call_id}/channels/{channel_name}/recording
```

Download the audio recording for a single side of a conversation in WAV format. This is useful when you want to analyze or store each speaker's audio separately.

### Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `call_id` | string | Yes | ID of the call |
| `channel_name` | string | Yes | Which channel to download: `"agent"` (your agent's audio), `"remote"` (the other party on the call, whether the call was inbound or outbound), or `"mixed"` (both sides combined, same as [Get conversation recording](#get-conversation-recording)). |

### Response

WAV audio file.

### Errors

| Status | Description |
| - | - |
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist, or no recording is available for this channel |
| 422 | `channel_name` is not one of `"agent"`, `"remote"`, or `"mixed"` |

### Example

```bash theme={null}
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  -o remote.wav \
  https://app.goguava.ai/v1/conversations/6064ab9663dc4eb0/channels/remote/recording
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.