# Search conversation items

> Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.

`POST /v2/api/conversations/items/search`

<Note>
**Required scope:** `CONVERSATIONS_READ`
</Note>

This endpoint is paginated. Use `page` and `size` in the request body to control results. See [Pagination](/docs/guides/pagination).

## Outbound calls that reached a voicemail

When an outbound call is answered by the contact's answering machine, `result` stays `ANSWERED`, because the carrier treats a machine pickup as an answer. Two fields carry the voicemail signal instead:

| Field | Meaning |
|-------|---------|
| `detected_outbound_voicemail` | A machine picked up (answering machine detection, or the transcript) |
| `voicemail_left` | A message was actually left after the beep |

Both are independent: `detected_outbound_voicemail: true` with `voicemail_left: false` means the call reached a voicemail and the caller hung up without leaving a message. Either can be `null` when that particular signal was never determined. `null` is not the same as `false`.

<Note>
Filtering by `result: "VOICEMAIL"` returns **inbound** voicemails only. To find outbound calls that reached a voicemail, search with `direction: "OUTBOUND"` and filter the returned items on `detected_outbound_voicemail`. There is no request filter for it.
</Note>

## Search behavior

The `search` field is a **keyword search**, not a natural language query. Extract keywords from the user's question before passing them.

| User asks | `search` value |
|-----------|---------------|
| "Find calls where customers complained about billing" | `"billing complaint"` |
| "What did we discuss about the refund policy?" | `"refund policy"` |
| "Show me conversations mentioning enterprise pricing" | `"enterprise pricing"` |

**How matching works:**

- Terms are **AND'd**: `"billing refund"` matches items containing **both** words
- **Prefix matching** is used: `"bill"` matches "billing", "billed", etc.
- Searches across: call transcripts, call summaries, and SMS message content
- Use `sort=RELEVANCE` to rank results by match quality instead of date

## Filter by type

| `type` | Returns |
|--------|---------|
| `ALL` (default) | Calls and messages |
| `CALL` | Calls only |
| `SMS` | Messages, faxes included |
| `FAX` | Faxes only |

A fax is returned as an item of `type` `SMS` with `message_type` `FAX`. See [Faxes](/docs/conversations/get-item#faxes).

## Field notes

| Field | Null when |
|-------|-----------|
| `summary` | SMS items, or calls where AI summary is not yet available |
| `duration` | SMS items (only applies to calls) |
| `result` | SMS items (only applies to calls) |
| `detected_outbound_voicemail` | Inbound calls, SMS items, or outbound calls where no detection ran |
| `voicemail_left` | Inbound calls, SMS items, or outbound calls where it was not determined |
| `recording_url` | Recording disabled, call not answered, SMS items, or accounts sold under a white-label partner's brand |
| `recording_download_url` | Accounts not created by a partner, calls on a HIPAA-enabled team, calls without a recording, a key user who cannot play the recording, or SMS items |
| `recording_download_expires_at` | Same as `recording_download_url` |
| `recording_duration` | Recording disabled, call not answered, or SMS items |
| `transcript` | Not requested via `extend=transcript`, or SMS items |
| `content` | Call items (only applies to SMS) |
| `status` | Call items (only applies to SMS) |
| `attachments` | Call items. An SMS with no photo or file returns an empty array. |
| `page_count` | Calls, messages that are not faxes, or a fax whose page count is not known yet |
| `tags` | SMS items (tags only apply to calls) |

`duration` is the total call length in seconds, ringing included. `recording_duration` is the talk time, which is what the Allo app displays for recorded calls. For calls without a recording, the app falls back to `duration`.

`recording_download_url` downloads the recording file with no Allo login, for 48 hours. It is returned only on lines of accounts created by a partner, never for a HIPAA call. See [Recording links](/docs/conversations/get-item#recording-links).

`attachments` lists the photos and other files of an MMS, each with a `download_url` valid for 30 minutes. See [MMS attachments](/docs/conversations/get-item#mms-attachments).

### Extend parameter

| Value | Effect |
|-------|--------|
| `transcript` | Include full call transcripts on each item |

Passing an unsupported value returns a `400` error with code `UNSUPPORTED_EXTEND_VALUE`.
