Search conversation histories

Performs semantic vector search across conversation history records.

How it works:

The query text is embedded into a 1024-dimensional vector using the multilingual-e5-large model.
The vector is sent to regional OpenSearch clusters for kNN search using HNSW cosine similarity.
When no region is specified, all regions are queried in parallel (fan-out) and results are merged by score.
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

GET

conversation_histories

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.ai.searchConversationHistories({
  q: 'customer called about billing issue',
  record_type: 'voice',
});

console.log(response.data);

{
  "data": [
    {
      "id": "rec-001_chunk_0",
      "record_id": "rec-001",
      "chunk_index": 0,
      "chunk_total": 3,
      "text": "Customer called regarding a billing discrepancy on their latest invoice. Agent confirmed the charge was correct and explained the prorated amount.",
      "score": 0.92,
      "record_type": "voice",
      "region": "USA",
      "user_id": "user-123",
      "organization_id": "org-456",
      "document_id": null,
      "record_created_at": "2026-05-28T12:00:00Z",
      "ingested_at": "2026-05-28T12:01:00Z",
      "metadata": {
        "source": "call-center",
        "language": "en"
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_results": 1,
    "page_number": 1,
    "page_size": 20
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

string

required

Natural language search query. The text is embedded into a 1024-dimensional vector and compared against indexed record chunks using kNN cosine similarity.

Minimum string length: 1

Example:

"customer called about billing issue"

record_type

enum<string>

required

The type of records to search. Each record type is stored in a separate vector index.

Available options:

voice,

message,

ai_pipeline_storage,

knowledge_base

Example:

"voice"

region

enum<string>

Restrict search to a specific region's OpenSearch cluster. When omitted, all regions are queried in parallel (fan-out) and results are merged by cosine similarity score.

Available options:

USA,

DEU,

AUS,

UAE

Example:

"USA"

top_k

integer

default:20

Maximum number of results to return. Defaults to 20, maximum 100.

Required range: 1 <= x <= 100

Example:

10

min_score

number<float>

default:0

Minimum cosine similarity score threshold (0.0 to 1.0). Results below this threshold are excluded.

Required range: 0 <= x <= 1

Example:

0.5

filter[user_id]

string

Filter to records owned by a specific user (exact match).

Example:

"user-123"

filter[record_id]

string

Filter to chunks belonging to a specific parent record (exact match).

Example:

"rec-001"

filter[document_id]

string

Filter by document identifier (exact match). Populated for knowledge_base records.

Example:

"doc-789"

filter[region][in]

string

Filter by the region stored on the record. Comma-separated to match multiple regions (USA, DEU, AUS, UAE). Distinct from the region parameter, which selects which cluster(s) are queried.

Example:

"USA,DEU"

filter[record_created_at][gte]

string<date-time>

Only include records whose original creation time is on or after this ISO 8601 timestamp.

Example:

"2026-01-01T00:00:00Z"

filter[record_created_at][lte]

string<date-time>

Only include records whose original creation time is on or before this ISO 8601 timestamp.

Example:

"2026-12-31T23:59:59Z"

filter[ingested_at][gte]

string<date-time>

Only include records ingested (chunked, embedded, and indexed) on or after this ISO 8601 timestamp.

Example:

"2026-01-01T00:00:00Z"

filter[ingested_at][lte]

string<date-time>

Only include records ingested (chunked, embedded, and indexed) on or before this ISO 8601 timestamp.

Example:

"2026-12-31T23:59:59Z"

filter[retention]

string

Filter by retention policy (exact match). Filter-only: not returned in the response body.

Response

Successful search response with ranked conversation history chunks.

Search response following the standard Telnyx V2 API format.

data

object[]

required

Ranked list of matching text chunks, sorted by cosine similarity score descending.

Show child attributes