---
title: Search and Answer
description: Choose ranked spans or a grounded answer with citations.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Search and Answer

Search retrieves ranked files or passages and the spans that matched. Answer uses collection content to write an answer with citations. Both operations stay within one collection and apply its access rules.

## Spans or answer

*Illustration: The same incident report can produce a Search hit or support an answer. Search returns spans. Answer links answer markers to spans through its sources list.*

Use Search when your application needs to choose or display results. A hit includes the file, rank, score, and spans. Use Answer when it needs an answer with citations. Search never writes an answer.

## Search controls

`hybrid` is the default. It matches exact words and meaning together. `keyword` matches exact words only: use it for IDs, codes, and error strings. `interpretation: "literal"` uses the supplied query as written. `natural_language` can interpret the query and add filters. Interpretation still returns Search results rather than an answer.

`result_type: "file"` groups matching passages by file, with up to three spans. `passage` returns one span per result. Both rows have the same fields. A span names `pages` (from 1), `chars` (Unicode code points, from 0), `seconds` (from 0), or the whole `file`. It holds no content: [Read spans](/engine/reference/read-spans) returns the content of up to 50 spans in one call. `include` picks the parts: `text` (the default) for the text or the speech, `raw` for the span in its own format, such as a PDF of the pages, the image, or a clip, and `file` for the whole file.

Scores support ranking within the response. They are not confidence percentages. A filter selects application data; it does not authorize a reader. See [Search files](/engine/guides/search).

## Answer effort and history

Answer runs one retrieve-and-answer pass within 45 seconds. `effort` is `medium` (the default) or `high`: `high` reads more and takes longer. For deep, many-step work, start a [research run](/engine/guides/research), which allows 600 seconds. `answer.efforts` in `/info` lists the efforts of your cluster. Answer and Research stay within the chosen collection and permitted content.

Your application stores conversation state. To supply context, send prior `user` and `assistant` messages in `history`, oldest first. Send the new question in `query`. The API does not store a conversation or accept a conversation ID.

## Citations connect the answer to content

**Answer and sources**

```json
{
  "request_id": "req_example_answer",
  "answer": "Checkout stalled because the service exhausted its connection pool [[SRC:0001]].",
  "effort": "medium",
  "sources": [
    {
      "ref": "SRC:0001",
      "span": {
        "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
        "unit": "chars",
        "start": 0,
        "end": 67
      },
      "path": "/incidents/checkout.txt",
      "content_type": "text/plain",
      "score": 0.81,
      "cited": true
    }
  ],
  "image_description": null,
  "usage": {
    "credits": 1
  }
}
```

An answer uses markers such as `[[SRC:0001]]`. Find the source whose `ref` is `SRC:0001` to render the corresponding citation. Each source provides a ref, a span, a path, a content type, a score, and `cited`.

`sources` selects the source list: `all` (the default) lists the cited sources and then the other retrieved sources, `cited` lists only the cited sources, and `none` returns an empty list and an answer with no markers. See [Answer](/engine/guides/answer).

## Answer now or research later

Answer holds the HTTP connection open until the answer is ready. A research run takes the Answer fields except `effort`, plus `web_search`, returns `202` at once, and works on the answer by itself. Follow the run with `research.progress` and `research.updated` events, or read it with GET. Use research for a question that can take minutes. See [Research](/engine/guides/research).
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.