> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Search files

Search files [#search-files]

Ask a question across your uploaded files, or only within chosen files and folders, and get the most relevant passages back.

`POST /search` returns the most relevant text chunks, each with its source `file_id`, score, and metadata such as page or content type when available.

Reference [#reference]

Request fields [#request-fields]

| Field     | Description                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------------- |
| `query`   | The question or search text.                                                                                     |
| `top_k`   | Chunks to return, 1 to 100. Default `5`.                                                                         |
| `filters` | Optional file, folder, or metadata filters; see [Filters](#filters).                                             |
| `rerank`  | Improves result ordering. Default `true`; set `false` for a faster response when approximate ordering is enough. |

Filters [#filters]

| Filter                                                      | Searches                                                                 |
| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
| `file_ids`                                                  | The listed files, e.g. the ones the user selected.                       |
| `folder_ids`                                                | A folder and its contents. The literal `root` searches root-level files. |
| Metadata produced during processing, e.g. `"type": "table"` | Chunks with that metadata, e.g. table-heavy files.                       |

* If you pass both `file_ids` and `folder_ids`, a chunk matches when its file is in either: one of the listed files or inside one of the folders.
* If you pass `file_ids` or `folder_ids` but every list you pass is empty, the response has no chunks.
* Metadata filters apply on top of the file and folder scope.

Response [#response]

| Field        | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `query`      | The query you sent.                                                      |
| `chunks`     | The results, each with `id`, `file_id`, `text`, `score`, and `metadata`. |
| `latency_ms` | Time the search took, in milliseconds.                                   |

Search all files [#search-all-files]

1. To search, wait until your files finish processing, then send `POST /search` with a `query` and `top_k`.

   ```python title="Python"
   import httpx

   FILES_URL = "https://alo-files-service-103105631559.europe-west8.run.app"
   HEADERS = {
       "X-API-Key": "sk-your-api-key",
       "X-Space-Slug": "acme",
   }

   result = httpx.post(
       f"{FILES_URL}/search",
       headers=HEADERS,
       json={
           "query": "What termination rights are in the supplier contracts?",
           "top_k": 5,
       },
   ).json()

   for chunk in result["chunks"]:
       print(chunk["file_id"], chunk["text"][:200])
   ```

2. To use the results, read `chunks`: each chunk has its `id`, text, its source `file_id`, a score, and metadata such as page or content type when available.

Search selected files or folders [#search-selected-files-or-folders]

1. To limit the search, add `filters` to the request: `file_ids` searches the listed files, and `folder_ids` searches a folder and its contents (`root` for root-level files). If you pass both, results come from either.

   ```json
   {
     "query": "Summarize the commercial terms",
     "filters": {
       "file_ids": ["4a6fbf7d-4d0f-4636-9a5d-06c80c0d8d89"]
     }
   }
   ```

Troubleshooting [#troubleshooting]

Search returns `503` [#search-returns-503]

The search did not finish within its time limit (60 seconds by default). The body has `code` `resource_busy` and `details.retryable` `true`; retry the request.