---
title: Search
description: Retrieve ranked files and passages with evidence.
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, inspect evidence, 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 evidence grouped by file or passage. Each result carries the file identity and a location that your application can use to open the source.*

## 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 <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "query": "checkout requests stall after deployment",
  "mode": "semantic",
  "interpretation": "literal",
  "result_unit": "file",
  "limit": 10
}
```

**200 OK**

```json
{
  "request_id": "req_example_search",
  "index_generation": "generation-example",
  "execution": {
    "mode": "semantic",
    "interpretation": "literal",
    "stages": [
      "semantic"
    ]
  },
  "results": [
    {
      "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "path": "/incidents/checkout.txt",
      "content_type": "text/plain",
      "rank": 1,
      "score": 0.81,
      "matched_by": [
        "semantic"
      ],
      "evidence": [
        {
          "kind": "text",
          "text": "Checkout stalled because the service exhausted its connection pool.",
          "location": {
            "char_start": 0,
            "char_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 unit

| Option | Use it for |
| --- | --- |
| `mode: "semantic"` | Matching a concept even when the file uses different wording. This is the default. |
| `mode: "keyword"` | Matching words and terms in the content. |
| `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_unit: "file"` | One grouped result per matching file. This is the default. |
| `result_unit: "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 evidence. Use Query for a written answer.

## Render evidence

Show the result path and supporting evidence together. `rank` is the relevance position. `score` is a ranking value, not a probability. `matched_by` identifies the retrieval mode that matched the evidence.

| Evidence location | How to use it |
| --- | --- |
| `char_start`, `char_end` | Locate a text span in the source. |
| `page`, optional `bbox` | Open the cited page and, when supplied, its region. |
| `start_ms`, `end_ms` | Seek to the passage in audio or video. Values are milliseconds. |
| `json_path` | Locate a value in structured JSON. |

A location can be absent. Keep the evidence text and file link useful without it. Reading the file or its content requires the key’s `read` action, even when Search itself is allowed.

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