--- title: Search description: Retrieve ranked files and passages with the spans that matched. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Search Build a results interface with ranked files or passages. Choose a retrieval mode, read the spans that matched, and handle empty or incomplete collections. ## Before you begin You need a collection with ready files and a key with `search` access. This example uses the collection from [Get started](/engine/get-started). It has access control off, so the request omits principals. *Illustration: Search returns spans grouped by file or passage. A span names a file and a place in it that your application can open or read.* ## Send a Search request **POST https://engine.example.com/namespaces/acme/collections/incident-logs:search** ```http POST /namespaces/acme/collections/incident-logs:search HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "query": "checkout requests stall after deployment", "mode": "hybrid", "interpretation": "literal", "result_type": "file", "limit": 10 } ``` **200 OK** ```json { "request_id": "req_example_search", "index_generation": "generation-example", "execution": { "mode": "hybrid", "interpretation": "literal" }, "results": [ { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "path": "/incidents/checkout.txt", "content_type": "text/plain", "rank": 1, "score": 0.81, "spans": [ { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "unit": "chars", "start": 0, "end": 67 } ] } ], "timing_ms": { "retrieval": 34, "total": 47 }, "warnings": [], "next_cursor": null } ``` `query` must contain a non-space character and is limited to 32,000 characters. `limit` controls the page size, from 1 to 100. Its default is 10. `next_cursor` continues the search; null marks the end. ## Choose a mode and result type | Option | Use it for | | --- | --- | | `mode: "hybrid"` | Matching exact words and meaning together, even when the file uses different wording. This is the default. | | `mode: "keyword"` | Matching exact words only, such as IDs, codes, and error strings. | | `interpretation: "literal"` | Using the supplied query directly. This is the default. | | `interpretation: "natural_language"` | Allowing interpretation to extract search text and filters from a sentence. | | `result_type: "file"` | One grouped result per matching file. This is the default. | | `result_type: "passage"` | Individual matching passages. A file can supply several results. | The selected mode must appear in `/info` and be enabled in the collection’s processing profile. Natural-language interpretation still returns spans. Use [Answer](/engine/guides/answer) for a written answer. ## Render spans Every result has the same fields. A `file` result holds `spans`: the places that matched, best first, at most three. A `passage` result holds one span in `spans`. `rank` is the relevance position. `score` is a ranking value, not a probability. | Span unit | What `start` and `end` count | | --- | --- | | `pages` | Pages of a section or a figure of a PDF or an office file, from 1. Page 7 is `start: 7, end: 8`. | | `chars` | Unicode code points in the text form of the file, from 0. On a PDF or an office file, the span also has `pages`: the pages that the chars cover, from 1. | | `seconds` | Whole seconds of a video or an audio file, from 0. | | `file` | The whole file, such as an image. The span has no `start` or `end`. | Every span is `[start, end)`: `end` is the first unit after the span. A span holds no content. Send up to 50 spans to [Read spans](/engine/reference/read-spans), and get one result for each span, in order. `include` names the parts of each result. `text` (the default) returns the text of a document, or the transcript lines of a video or an audio file. `raw` returns the span cut from the file in its own format: a PDF of the pages, the text of a text file or a mail, the image, or a clip. `file` returns the whole file. With `text`, `raw` is cut to the span of the text. A binary part comes back inline as base64 `data` until the call reaches its inline limit. Past that, or with `delivery: "url"`, it comes back as a signed `url`. The result `span` uses the unit of the content: the text of pages comes back as `chars` with `pages`. A large span comes back in parts: `next` is the body of the next request, with the same `include` and `delivery`. Send it until `next` is null. A span that cannot be read has an `error` on its own result. The other spans still read. `text` needs the key’s `search` action. `raw` and `file` also need `read`. **POST https://engine.example.com/namespaces/acme/collections/incident-logs:read-spans** ```http POST /namespaces/acme/collections/incident-logs:read-spans HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "spans": [ { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "unit": "chars", "start": 0, "end": 67 } ], "include": [ "text" ] } ``` **200 OK** ```json { "request_id": "req_example_read_spans", "results": [ { "span": { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "unit": "chars", "start": 0, "end": 67 }, "content_type": "text/plain", "text": "Checkout stalled because the service exhausted its connection pool." } ], "next": null } ``` ## Handle collection states An empty collection or a query with no matches returns `200` and `results: []`. A collection with no ready files while indexing returns `409 collection_not_ready`. Wait for completion events before another request. If every file failed, Search returns `200`, no results, and a `collection_failed` warning. Show that warning rather than treating it as proof that the topic is absent. A degraded collection can return results from its ready files. Add [filters and pagination](/engine/guides/filter-and-paginate) to refine results. For an enforced collection, follow [Apply access rules](/engine/guides/access-rules). The [Search reference](/engine/reference/search-collection) lists every request and response field. ## Sitemap See the full [sitemap](/sitemap.md) for all pages.