Search collection documents

Runs search over the documents in a collection, ranked by relevance to query. The collection’s retrieval_type setting selects the strategy: vector (semantic similarity), hybrid (vector similarity fused with keyword matching), or keyword (lexical BM25 matching). When query is omitted, returns a plain catalog listing of the collection’s documents.

How it works:

For vector and hybrid, the query text is embedded into a 1024-dimensional vector using the multilingual-e5-large model.
For vector, the embedding is compared against the collection’s indexed document chunks using semantic similarity; for hybrid, those similarity scores are fused with keyword-match scores; for keyword, only lexical BM25 matching is applied.
Results are ranked by score (descending) and paginated via page[number] / page[size].

Authentication: Requires a Telnyx API key via Authorization: Bearer <key>. Results are automatically scoped to your organization and cannot be overridden.

Filtering: Use filter[field][operator]=value query parameters to narrow results before search. Supported operators: eq (default), in, gte, gt, lte, lt, contains. Metadata fields resolve to metadata.<field>.

Examples:

GET /v2/ai/collections/my-collection/documents?query=billing+issue&top_k=10
GET /v2/ai/collections/my-collection/documents?query=refund&sources=voice,message
GET /v2/ai/collections/my-collection/documents?query=outage&filter[record_created_at][gte]=2026-01-01T00:00:00Z

GET

collections

{slug}

documents

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.collections.retrieveDocuments('slug');

console.log(response.data);

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.collections.retrieve_documents(
    "slug",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.AI.Collections.GetDocuments(
		context.TODO(),
		"slug",
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

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

public final class Main {
    private Main() {}

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

        var response = client.ai().collections().retrieveDocuments("slug");
    }
}

<?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->collections->retrieveDocuments(
    'slug',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "data": [
    {
      "id": "<string>",
      "record_id": "<string>",
      "record_type": "voice",
      "chunk_index": 123,
      "chunk_total": 123,
      "text": "<string>",
      "score": 123,
      "region": "<string>",
      "user_id": "<string>",
      "organization_id": "<string>",
      "record_created_at": "2023-11-07T05:31:56Z",
      "ingested_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "meta": {
    "collection_slug": "support-transcripts",
    "searched_sources": [
      "voice",
      "message"
    ],
    "retrieval_type": "vector",
    "top_k": 5,
    "total_results": 42,
    "total_pages": 3,
    "page_number": 1,
    "page_size": 20
  }
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "The request failed because it was not well-formed.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10009",
      "title": "Authentication failed",
      "detail": "The required authentication headers were either invalid or not included in the request.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10009"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10005",
      "title": "Resource not found",
      "detail": "The requested resource or URL could not be found.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10005"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10027",
      "title": "Unprocessable Entity",
      "detail": "The server understood the syntax of the request but was unable to process the instructions.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10027"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.

Path Parameters

slug

string

required

The collection's slug (unique within your organization).

Example:

"support-transcripts"

Query Parameters

query

string

Natural-language search query. When provided, the text is matched against the collection's document chunks using the collection's retrieval_type (vector or hybrid). When omitted, documents are returned as a plain catalog listing.

Minimum string length: 1

Example:

"customer called about billing issue"

top_k

integer

Maximum number of ranked results to consider. When omitted, the collection's configured top_k setting is used.

Required range: 1 <= x <= 50

Example:

10

sources

string

Comma-separated list of source types to restrict the search to. When omitted, all of the collection's sources are searched.

Example:

"voice,message"

retrieval_type

enum<string>

Override the collection's configured retrieval strategy for this request. Echoed back in meta.retrieval_type.

Available options:

vector,

hybrid,

keyword

Example:

"hybrid"

filter

object

Field filters applied before ranking, using filter[field][operator]=value. Supported operators: eq (default), in, gte, gt, lte, lt, contains. Known fields: record_type, record_id, user_id, record_created_at, ingested_at; any other name resolves to a metadata.<field> filter. Example: filter[record_id][eq]=rec_123.

page[number]

integer

default:1

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

Required range: x >= 1

Example:

1

page[size]

integer

default:20

Number of results per page. Defaults to 20.

Required range: 1 <= x <= 100

Example:

20

Response

Ranked (or listed) collection documents.

data

object[]

Show child attributes

meta

object

Show child attributes

⌘I

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.collections.retrieveDocuments('slug');

console.log(response.data);

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.collections.retrieve_documents(
    "slug",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.AI.Collections.GetDocuments(
		context.TODO(),
		"slug",
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

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

public final class Main {
    private Main() {}

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

        var response = client.ai().collections().retrieveDocuments("slug");
    }
}

<?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->collections->retrieveDocuments(
    'slug',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "data": [
    {
      "id": "<string>",
      "record_id": "<string>",
      "record_type": "voice",
      "chunk_index": 123,
      "chunk_total": 123,
      "text": "<string>",
      "score": 123,
      "region": "<string>",
      "user_id": "<string>",
      "organization_id": "<string>",
      "record_created_at": "2023-11-07T05:31:56Z",
      "ingested_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "meta": {
    "collection_slug": "support-transcripts",
    "searched_sources": [
      "voice",
      "message"
    ],
    "retrieval_type": "vector",
    "top_k": 5,
    "total_results": 42,
    "total_pages": 3,
    "page_number": 1,
    "page_size": 20
  }
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "The request failed because it was not well-formed.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10009",
      "title": "Authentication failed",
      "detail": "The required authentication headers were either invalid or not included in the request.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10009"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10005",
      "title": "Resource not found",
      "detail": "The requested resource or URL could not be found.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10005"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10027",
      "title": "Unprocessable Entity",
      "detail": "The server understood the syntax of the request but was unable to process the instructions.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10027"
      }
    }
  ]
}

Search

Concepts

Configuration

API

For AI Agents

Search collection documents

Authorizations

Path Parameters

Query Parameters

Response