> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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
```



## OpenAPI

````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/ai/conversation-histories.yml get /ai/conversation_histories
openapi: 3.1.0
info:
  title: Telnyx AI Conversation Histories API
  version: 2.0.0
  description: >-
    Semantic vector search across conversation history records (voice, message,
    AI pipeline storage, and knowledge base).
  contact:
    email: support@telnyx.com
servers:
  - url: https://api.telnyx.com/v2
security:
  - bearerAuth: []
paths:
  /ai/conversation_histories:
    get:
      tags:
        - Conversation Histories
      summary: Search conversation histories
      description: >-
        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

        ```
      operationId: SearchConversationHistories
      parameters:
        - name: q
          in: query
          required: true
          description: >-
            Natural language search query. The text is embedded into a
            1024-dimensional vector and compared against indexed record chunks
            using semantic similarity.
          schema:
            type: string
            minLength: 1
            example: customer called about billing issue
        - name: region
          in: query
          required: false
          description: >-
            Restrict search to a specific region. When omitted, all regions are
            queried in parallel (fan-out) and results are merged by similarity
            score.
          schema:
            type: string
            enum:
              - USA
              - DEU
              - AUS
              - UAE
            example: USA
        - name: page[number]
          in: query
          required: false
          description: Page number to return (1-based). Defaults to 1.
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: page[size]
          in: query
          required: false
          description: Number of results per page. Defaults to 20, maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 10
        - name: min_score
          in: query
          required: false
          description: >-
            Minimum cosine similarity score threshold (0.0 to 1.0). Results
            below this threshold are excluded.
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
            default: 0
            example: 0.5
        - name: filter[user_id]
          in: query
          required: false
          description: Filter to records owned by a specific user (exact match).
          schema:
            type: string
            example: user-123
        - name: filter[record_id]
          in: query
          required: false
          description: >-
            Filter to chunks belonging to a specific parent record (exact
            match).
          schema:
            type: string
            example: rec-001
        - name: filter[region][in]
          in: query
          required: false
          description: >-
            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.
          schema:
            type: string
            example: USA,DEU
        - name: filter[record_created_at][gte]
          in: query
          required: false
          description: >-
            Only include records whose original creation time is on or after
            this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
            example: '2026-01-01T00:00:00Z'
        - name: filter[record_created_at][lte]
          in: query
          required: false
          description: >-
            Only include records whose original creation time is on or before
            this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
            example: '2026-12-31T23:59:59Z'
        - name: filter[ingested_at][gte]
          in: query
          required: false
          description: >-
            Only include records ingested (chunked, embedded, and indexed) on or
            after this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
            example: '2026-01-01T00:00:00Z'
        - name: filter[ingested_at][lte]
          in: query
          required: false
          description: >-
            Only include records ingested (chunked, embedded, and indexed) on or
            before this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
            example: '2026-12-31T23:59:59Z'
        - name: filter[retention]
          in: query
          required: false
          description: >-
            Filter by retention policy (exact match). Filter-only: not returned
            in the response body.
          schema:
            type: string
      responses:
        '200':
          description: Successful search response with ranked conversation history chunks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationHistoryResponse'
              example:
                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
                    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: 1
                  page_number: 1
                  page_size: 20
        '400':
          description: >-
            Invalid request parameters — invalid region or malformed filter
            expression.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transcriptions-search_Errors'
              example:
                errors:
                  - code: '400'
                    title: Bad Request
                    detail: >-
                      Invalid region: invalid. Must be one of: USA, DEU, AUS,
                      UAE
        '401':
          description: >-
            Missing or invalid authentication. Provide a valid Telnyx API key
            via the Authorization: Bearer header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transcriptions-search_Errors'
              example:
                errors:
                  - code: '10004'
                    title: Authentication failed
                    detail: >-
                      The required authentication headers were either invalid or
                      not included in the request.
        '422':
          description: Request validation failed (e.g., missing required parameter).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transcriptions-search_Errors'
        '500':
          description: >-
            Server-side error — embeddings service unavailable, search backend
            unreachable, or internal processing failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transcriptions-search_Errors'
              example:
                errors:
                  - code: '10007'
                    title: Unexpected error
                    detail: An unexpected error occured.
                    meta:
                      url: https://developers.telnyx.com/docs/overview/errors/10007
        '503':
          description: Service not initialized — bootstrap still in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transcriptions-search_Errors'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            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',
            });

            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from telnyx import Telnyx

            client = Telnyx(
                api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
            )
            response = client.ai.search_conversation_histories(
                q="customer called about billing issue",
            )
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.AI.SearchConversationHistories(context.TODO(), telnyx.AISearchConversationHistoriesParams{\n\t\tQ: \"customer called about billing issue\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: >-
            package com.telnyx.sdk.example;


            import com.telnyx.sdk.client.TelnyxClient;

            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

            import com.telnyx.sdk.models.ai.AiSearchConversationHistoriesParams;

            import
            com.telnyx.sdk.models.ai.AiSearchConversationHistoriesResponse;


            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    TelnyxClient client = TelnyxOkHttpClient.fromEnv();

                    AiSearchConversationHistoriesParams params = AiSearchConversationHistoriesParams.builder()
                        .q("customer called about billing issue")
                        .build();
                    AiSearchConversationHistoriesResponse response = client.ai().searchConversationHistories(params);
                }
            }
        - lang: Ruby
          source: >-
            require "telnyx"


            telnyx = Telnyx::Client.new(api_key: "My API Key")


            response = telnyx.ai.search_conversation_histories(q: "customer
            called about billing issue")


            puts(response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Telnyx\Client;

            use Telnyx\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API
            Key');


            try {
              $response = $client->ai->searchConversationHistories(
                q: 'customer called about billing issue',
                filterIngestedAtGte: new \DateTimeImmutable('2026-01-01T00:00:00Z'),
                filterIngestedAtLte: new \DateTimeImmutable('2026-12-31T23:59:59Z'),
                filterRecordCreatedAtGte: new \DateTimeImmutable('2026-01-01T00:00:00Z'),
                filterRecordCreatedAtLte: new \DateTimeImmutable('2026-12-31T23:59:59Z'),
                filterRecordID: 'rec-001',
                filterRegionIn: 'USA,DEU',
                filterRetention: 'filter[retention]',
                filterUserID: 'user-123',
                minScore: 0.5,
                pageNumber: 1,
                pageSize: 10,
                region: 'USA',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx ai search-conversation-histories \
              --api-key 'My API Key' \
              --q 'customer called about billing issue'
components:
  schemas:
    ConversationHistoryResponse:
      type: object
      description: Search response following the standard Telnyx V2 API format.
      required:
        - data
        - meta
      properties:
        data:
          type: array
          description: >-
            Ranked list of matching text chunks, sorted by cosine similarity
            score descending.
          items:
            $ref: '#/components/schemas/ConversationHistoryRecord'
        meta:
          $ref: '#/components/schemas/transcriptions-search_PaginationMeta'
    transcriptions-search_Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/transcriptions-search_Error'
    ConversationHistoryRecord:
      type: object
      description: >-
        A single search result representing one chunk of a conversation history
        record. Records are split into chunks of up to 480 tokens with 64-token
        overlap at ingestion time.
      required:
        - id
        - record_id
        - chunk_index
        - chunk_total
        - text
        - score
        - region
        - user_id
        - organization_id
        - record_created_at
        - ingested_at
      properties:
        id:
          type: string
          description: Unique chunk identifier.
          example: rec-001_chunk_0
        record_id:
          type: string
          description: >-
            Identifier of the parent record. Multiple chunks from the same
            record share this ID.
          example: rec-001
        chunk_index:
          type: integer
          description: Zero-based index of this chunk within the parent record.
          example: 0
        chunk_total:
          type: integer
          description: Total number of chunks the parent record was split into.
          example: 3
        text:
          type: string
          description: The text content of this chunk (up to 480 tokens).
          example: >-
            Customer called regarding a billing discrepancy on their latest
            invoice.
        score:
          type: number
          format: float
          description: >-
            Cosine similarity score between the query vector and this chunk's
            vector. Higher values indicate greater semantic relevance.
          example: 0.92
        region:
          type: string
          enum:
            - USA
            - DEU
            - AUS
            - UAE
          description: The region where this record is stored.
          example: USA
        user_id:
          type: string
          description: Identifier of the user who owns this record.
          example: user-123
        organization_id:
          type: string
          description: Identifier of the organization that owns this record.
          example: org-456
        record_created_at:
          type: string
          format: date-time
          description: When the original record was created (ISO 8601).
          example: '2026-05-28T12:00:00Z'
        ingested_at:
          type: string
          format: date-time
          description: When the record was chunked, embedded, and indexed (ISO 8601).
          example: '2026-05-28T12:01:00Z'
        metadata:
          type: object
          additionalProperties: true
          default: {}
          description: >-
            Arbitrary metadata attached to the record at ingestion time.
            Filterable via filter[field]=value query parameters.
          example:
            source: call-center
            language: en
    transcriptions-search_PaginationMeta:
      type: object
      description: Pagination metadata following the standard Telnyx V2 API format.
      required:
        - total_pages
        - total_results
        - page_number
        - page_size
      properties:
        total_pages:
          type: integer
          description: Total number of pages.
          example: 1
        total_results:
          type: integer
          description: Total number of matching results across all queried regions.
          example: 42
        page_number:
          type: integer
          description: Current page number (1-based), matching the requested page[number].
          example: 1
        page_size:
          type: integer
          description: Number of results per page, matching the requested page[size].
          example: 20
    transcriptions-search_Error:
      type: object
      properties:
        code:
          type: string
        title:
          type: string
        detail:
          type: string
        meta:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````