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

# How Search Works

> How Search indexes your Telnyx data and retrieves ranked chunks at query time -- and when to use it over the raw embeddings APIs.

Search has two core processes: **indexing**, which turns your content into searchable chunks continuously in the background, and **querying**, which retrieves the most relevant chunks for a request. Understanding both explains why collections are cheap to create and why search results look the way they do.

## How Indexing Works

Each source system owns its own ingestion -- content becomes searchable without any per-collection work:

1. **Ingest** -- a data source is enabled for indexing. Voice transcriptions flow in as calls end, controlled by [conversation persistence](/docs/ai-search/sources/voice) -- a collection can only see what persistence has stored for the account.
2. **Chunk** -- each record (a transcript, a file) is split into chunks sized for retrieval. Chunks carry `chunk_index` and `chunk_total` so a full record can be [reassembled](/docs/ai-search/searching#reconstructing-a-document) later.
3. **Embed** -- each chunk is converted into a vector that captures its meaning, and stored in the source's vector database alongside its metadata (`record_id`, timestamps, origin fields).

New calls are searchable minutes after they end. There are no sync schedules to manage.

## How Querying Works

When you search a collection:

1. **Resolve the collection** -- the collection's [sources](/docs/ai-search/sources) and [settings](/docs/ai-search/settings) are looked up by slug; per-request parameters override settings for that request only.
2. **Embed the query** -- the query text is embedded with the same model family used at indexing time.
3. **Filter** -- any [`filter[field][op]`](/docs/ai-search/searching#field-filters) conditions are applied before nearest-neighbor search, so filters narrow the candidate set without distorting scores.
4. **Fan out** -- the search runs against every searchable source in the collection, across all regions where content is stored.
5. **Merge** -- per-source, per-region results are merged into one list ranked by relevance `score`, capped at `top_k`.
6. **Return chunks** -- each chunk carries its text, score, and source metadata. Search stops here by design: generation belongs to your application.

The whole fan-out counts as **one** billable search event, regardless of how many sources and regions were searched. See [Pricing](/docs/inference/embedding-rag/pricing).

## A Collection Is a Pointer

Creating a collection only writes configuration rows -- it does not copy, move, or re-embed content. This has practical consequences:

* Creation is instant, and a new collection over already-indexed sources is immediately searchable.
* Removing a source or deleting a collection drops only collection-scoped artifacts. The underlying Telnyx data is never modified or deleted.
* The same source can back many collections at no extra indexing cost.

## Search vs. the Embeddings APIs

Telnyx also ships lower-level building blocks -- the [Embeddings API](/docs/inference/embeddings) embeds documents in a Storage bucket, and `POST /v2/ai/embeddings/similarity-search` queries one bucket directly. Search is the managed layer above them:

|                  | Search                                            | Embeddings API                                                                              |
| ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| What it is       | Managed search product over your Telnyx data      | Bucket-level embedding primitives you compose yourself                                      |
| You give it      | Sources (`voice` today, more coming soon)         | One Storage bucket per request                                                              |
| Scope of a query | Every source in the collection, merged and ranked | A single embedded bucket                                                                    |
| Ingestion        | Continuous, owned by each source system           | You trigger embedding per bucket                                                            |
| Query surface    | `GET /v2/ai/collections/{slug}/documents`         | `POST /v2/ai/embeddings/similarity-search`                                                  |
| Grounded chat    | Bring your own LLM over search results            | `retrieval` tool on [chat completions](/docs/inference/embeddings#chat-over-your-documents) |
| Best when        | Searching your account's conversations            | You need direct control of one bucket's embeddings                                          |

If you are starting fresh, start with Search. Reach for the embeddings APIs when you need the primitive itself.