---
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 sent to regional OpenSearch clusters for kNN search using HNSW cosine similarity.
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 cosine similarity score (descending) and truncated to `top_k`.

**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`, `record_type`, `region`, `document_id`, `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>` in OpenSearch (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&record_type=voice&top_k=10
GET /v2/ai/conversation_histories?q=setup+guide&record_type=knowledge_base&region=USA&min_score=0.5
GET /v2/ai/conversation_histories?q=refund&record_type=voice&filter[record_created_at][gte]=2026-01-01T00:00:00Z
GET /v2/ai/conversation_histories?q=outage&record_type=voice&filter[region][in]=USA,DEU
GET /v2/ai/conversation_histories?q=hold+time&record_type=voice&filter[language]=en
```

## Query parameters

- `q` string, required
- `record_type` 'voice' | 'message' | 'ai_pipeline_storage' | 'knowledge_base', required
- `region` 'USA' | 'DEU' | 'AUS' | 'UAE'
- `top_k` integer
- `min_score` number, float
- `filter[user_id]` string
- `filter[record_id]` string
- `filter[document_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.
    - `id` string, required — Unique chunk identifier.
    - `record_id` string, required — Identifier of the parent record. Multiple chunks from the same record share this ID.
    - `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.
    - `text` string, required — The text content of this chunk (up to 480 tokens).
    - `score` number, float, required — Cosine similarity score between the query vector and this chunk's vector. Higher values indicate greater semantic relevance.
    - `record_type` 'voice' | 'message' | 'ai_pipeline_storage' | 'knowledge_base', required — Type of the record.
    - `region` 'USA' | 'DEU' | 'AUS' | 'UAE', required — The region where this record is stored.
    - `user_id` string, required — Identifier of the user who owns this record.
    - `organization_id` string, required — Identifier of the organization that owns this record.
    - `document_id` string, nullable, required — Document identifier. Present only for knowledge_base records; null for all other record types.
    - `record_created_at` string, date-time, required — When the original record was created (ISO 8601).
    - `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. Stored as a flat_object in OpenSearch and filterable via filter[field]=value query parameters.
  - `meta` TranscriptionsSearchPaginationMeta, required — Pagination metadata following the standard Telnyx V2 API format.
    - `total_pages` integer, required — Total number of pages.
    - `total_results` integer, required — Total number of matching results across all queried regions (before top_k truncation).
    - `page_number` integer, required — Current page number (always 1 — this API does not support pagination, use top_k instead).
    - `page_size` integer, required — Number of results per page (equals the effective top_k value).

## Other responses

- `400` — Invalid request parameters — unsupported record_type, 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, OpenSearch cluster unreachable, or internal processing failure.
- `503` — Service not initialized — bootstrap still in progress.

---

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