Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 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 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
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 semantic similarity.

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

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

page[number]integer
Example:1

Page number to return (1-based). Defaults to 1.

page[size]integer
Example:10

Number of results per page. 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[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": [
    {
      "chunk_total": 3,
      "id": "rec-001_chunk_0",
      "ingested_at": "2026-05-28T12:01:00Z",
      "metadata": {
        "language": "en",
        "source": "call-center"
      },
      "organization_id": "org-456",
      "record_created_at": "2026-05-28T12:00:00Z",
      "record_id": "rec-001",
      "region": "USA",
      "score": 0.92,
      "text": "Customer called regarding a billing discrepancy on their latest invoice.",
      "user_id": "user-123"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_results": 42
  }
}