> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Typeahead

> Prefix suggestions for a search box, drawn concurrently from field values, collection names, and the caller's own recent searches

`GET /v1/retrievers/typeahead` returns autocomplete suggestions for a prefix. It
queries three namespace-scoped sources concurrently and returns each separately,
plus one flat ranked list you can render directly.

```bash theme={null}
curl -sS "$MP_API_URL/v1/retrievers/typeahead?q=nik&fields=metadata.talent,metadata.production&limit=10" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS"
```

```json Response theme={null}
{
  "query": "nik",
  "suggestions": ["Nike", "Nikon", "nike-summer-2026"],
  "values": [
    { "field": "metadata.talent", "value": "Nike", "count": 412 },
    { "field": "metadata.production", "value": "Nikon", "count": 37 }
  ],
  "collections": [
    { "collection_id": "col_abc", "collection_name": "nike-summer-2026" }
  ],
  "recent_searches": ["nike hero cut"],
  "warnings": []
}
```

## Parameters

| Parameter | Meaning                                                                                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`       | Required. The typed prefix, 1 to 200 characters.                                                                                                                 |
| `fields`  | Comma-separated metadata field paths to suggest values from, for example `metadata.talent,metadata.production`. Omit it to skip the field-value source entirely. |
| `limit`   | 1 to 50, default 10.                                                                                                                                             |

<Warning>
  **`limit` is per source, not per response.** With all three sources answering,
  a `limit` of 10 can return up to 30 entries in `suggestions`. Size your UI
  against the total rather than the parameter.

  **At most 5 `fields` are consulted.** Passing more does not fail the request,
  so a sixth field simply never contributes suggestions and nothing says so.
  Each field also needs a keyword index to be searchable.
</Warning>

## Reading the response

| Field             | Contents                                                                |
| ----------------- | ----------------------------------------------------------------------- |
| `query`           | The prefix that was matched. Always present.                            |
| `suggestions`     | Flat ranked texts across all sources.                                   |
| `values`          | Field-value matches, each with `field`, `value` and a document `count`. |
| `collections`     | Matching collections, each with `collection_id` and `collection_name`.  |
| `recent_searches` | The caller's own recent queries, newest first.                          |
| `warnings`        | Sources that could not be consulted on this request.                    |

<Note>
  **A source that cannot answer is dropped, not fatal.** The request still
  returns 200 with whatever the other sources produced, and the one that failed
  is named in `warnings`.

  So a thin result set has two different causes: few matches, or a source that
  did not run. Read `warnings` to tell them apart. This is the one place the API
  tells you which of the two happened, and it costs one field to check.
</Note>

`recent_searches` is scoped to the calling identity, so two users typing the same
prefix get different suggestions from that source and identical suggestions from
the other two.

## Related

* [Search Widget](/docs/integrations/search-widget) for the prebuilt UI components
* [Retrievers](/docs/retrieval/retrievers) for running the search itself