Sign in

v47

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-181,0851,7264.5 MB
Conversation Histories

Search 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
get/ai/conversation_histories

Query parameters

qstring required
Example:customer called about billing issue

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

record_type'voice' | 'message' | 'ai_pipeline_storage' | 'knowledge_base' required
Example:voice

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

region'USA' | 'DEU' | 'AUS' | 'UAE'
Example:USA

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.

top_kinteger
Example:10

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

min_scorenumber float
Example:0.5

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

filter[user_id]string
Example:user-123

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

filter[record_id]string
Example:rec-001

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

filter[document_id]string
Example:doc-789

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

filter[region][in]string
Example:USA,DEU

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.

filter[record_created_at][gte]string date-time
Example:2026-01-01T00:00:00Z

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

filter[record_created_at][lte]string date-time
Example:2026-12-31T23:59:59Z

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

filter[ingested_at][gte]string date-time
Example:2026-01-01T00:00:00Z

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

filter[ingested_at][lte]string date-time
Example:2026-12-31T23:59:59Z

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

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.

Example response

{
  "data": [
    {
      "id": "rec-001_chunk_0",
      "record_id": "rec-001",
      "chunk_total": 3,
      "text": "Customer called regarding a billing discrepancy on their latest invoice.",
      "score": 0.92,
      "record_type": "voice",
      "region": "USA",
      "user_id": "user-123",
      "organization_id": "org-456",
      "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": 42,
    "page_number": 1,
    "page_size": 20
  }
}