Skip to main content
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 — 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 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 and 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] 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.

​
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 embeds documents in a Storage bucket, and POST /v2/ai/embeddings/similarity-search queries one bucket directly. Search is the managed layer above them: If you are starting fresh, start with Search. Reach for the embeddings APIs when you need the primitive itself.