---
title: "Search conversation histories"
method: GET
path: "/ai/conversation_histories"
tags: ["Conversation Histories"]
---

# Search conversation histories

`GET /ai/conversation_histories`

Performs semantic vector search across conversation history records.

**How it works:**
1. The query text is embedded into a 1024-dimensional vector using the multilingual-e5-large model.
2. The vector is compared against indexed record chunks using semantic similarity search.
3. When no region is specified, all regions are queried in parallel (fan-out) and results are merged by score.
4. Results are ranked by similarity score (descending) and paginated via `page[number]` / `page[size]`.

**Authentication:** Requires a Telnyx API key via `Authorization: Bearer <key>`. Results are automatically scoped to the caller's organization — `organization_id` is injected from the auth token and cannot be overridden.

**Chunking:** Records are split into chunks of up to 480 tokens with 64-token overlap at ingestion time. Each search result represents a single chunk, with `chunk_index` and `chunk_total` indicating its position within the original record.

**Filtering:** Use `filter[field][operator]=value` query parameters to narrow results before vector search.

Top-level filterable fields: `user_id`, `region`, `record_id`, `record_created_at`, `ingested_at`, `retention`

Note: `retention` is filter-only — it can be used to narrow results but is not returned in the response body.

Metadata fields: any field not in the list above is resolved to `data.metadata.<field>` (e.g., `filter[language]=en` → `data.metadata.language`).

Supported filter operators:
- `eq` — exact match (default when no operator specified)
- `in` — match any of comma-separated values
- `gte`, `gt`, `lte`, `lt` — range comparisons (useful for date filtering)
- `contains` — wildcard substring match

**Examples:**
- `GET /v2/ai/conversation_histories?q=billing+issue&page[size]=10`
- `GET /v2/ai/conversation_histories?q=setup+guide&region=USA&min_score=0.5`
- `GET /v2/ai/conversation_histories?q=refund&filter[record_created_at][gte]=2026-01-01T00:00:00Z`
- `GET /v2/ai/conversation_histories?q=outage&filter[region][in]=USA,DEU`
- `GET /v2/ai/conversation_histories?q=hold+time&filter[language]=en`

## Query parameters

- `q` string, required
- `region` 'USA' | 'DEU' | 'AUS' | 'UAE'
- `page[number]` integer
- `page[size]` integer
- `min_score` number, float
- `filter[user_id]` string
- `filter[record_id]` string
- `filter[region][in]` string
- `filter[record_created_at][gte]` string, date-time
- `filter[record_created_at][lte]` string, date-time
- `filter[ingested_at][gte]` string, date-time
- `filter[ingested_at][lte]` string, date-time
- `filter[retention]` string

## Response `200`

Successful search response with ranked conversation history chunks.

- ConversationHistoryResponse — Search response following the standard Telnyx V2 API format.
  - `data` ConversationHistoryRecord[], required — Ranked list of matching text chunks, sorted by cosine similarity score descending.
    - `chunk_index` integer, required — Zero-based index of this chunk within the parent record.
    - `chunk_total` integer, required — Total number of chunks the parent record was split into.
    - `id` string, required — Unique chunk identifier.
    - `ingested_at` string, date-time, required — When the record was chunked, embedded, and indexed (ISO 8601).
    - `metadata` object — Arbitrary metadata attached to the record at ingestion time. Filterable via filter[field]=value query parameters.
    - `organization_id` string, required — Identifier of the organization that owns this record.
    - `record_created_at` string, date-time, required — When the original record was created (ISO 8601).
    - `record_id` string, required — Identifier of the parent record. Multiple chunks from the same record share this ID.
    - `region` 'USA' | 'DEU' | 'AUS' | 'UAE', required — The region where this record is stored.
    - `score` number, float, required — Cosine similarity score between the query vector and this chunk's vector. Higher values indicate greater semantic relevance.
    - `text` string, required — The text content of this chunk (up to 480 tokens).
    - `user_id` string, required — Identifier of the user who owns this record.
  - `meta` TranscriptionsSearchPaginationMeta, required — Pagination metadata following the standard Telnyx V2 API format.
    - `page_number` integer, required — Current page number (1-based), matching the requested page[number].
    - `page_size` integer, required — Number of results per page, matching the requested page[size].
    - `total_pages` integer, required — Total number of pages.
    - `total_results` integer, required — Total number of matching results across all queried regions.

## Other responses

- `400` — Invalid request parameters — invalid region or malformed filter expression.
- `401` — Missing or invalid authentication. Provide a valid Telnyx API key via the Authorization: Bearer header.
- `422` — Request validation failed (e.g., missing required parameter).
- `500` — Server-side error — embeddings service unavailable, search backend unreachable, or internal processing failure.
- `503` — Service not initialized — bootstrap still in progress.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)