---
title: "Typeahead"
method: GET
path: "/v1/retrievers/typeahead"
tags: ["Retrievers"]
---

# Typeahead

`GET /v1/retrievers/typeahead`

Prefix suggestions for a search box (autocomplete/typeahead).

Suggests from three namespace-scoped sources concurrently: values of the
requested metadata fields (index-backed, with per-value document counts),
collection names, and the caller's own recent search queries. A source
that cannot answer is dropped and named in ``warnings`` rather than
failing the request.

## Query parameters

- `q` string, required — The typed prefix.
- `fields` string, nullable — Comma-separated metadata field paths to suggest values from (e.g. `metadata.talent,metadata.production`). Each field should carry a keyword index; at most 5 are consulted. Omit to skip the field-value source.
- `limit` integer — Max suggestions per source.

## Response `200`

Successful Response

- TypeaheadResponse — Prefix suggestions for a search box. Three sources, each scoped to the caller's namespace and organization: metadata-field values (index-backed facet, prefix-filtered), collection names, and the caller's own recent search queries. ``suggestions`` is the flat ranked convenience list (recent searches first, then field values by count, then collection names, case-insensitively deduplicated). A source that fails or times out is dropped and named in ``warnings`` instead of failing the request.
  - `query` string, required — The prefix that was matched.
  - `suggestions` string[] — Flat ranked suggestion texts across all sources.
  - `values` TypeaheadValueSuggestion[] — Field-value suggestions with per-value document counts.
    - `field` string, required — The metadata field path the value came from.
    - `value` string, required — The suggested value.
    - `count` integer, required — Documents carrying this value inside the caller's namespace.
  - `collections` TypeaheadCollectionSuggestion[] — Collections whose name matches the prefix.
    - `collection_id` string, required — Collection ID.
    - `collection_name` string, required — Collection name.
  - `recent_searches` string[] — The caller's own recent queries matching the prefix, newest first.
  - `warnings` string[] — Sources that could not be consulted this request.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-08-23** `5307993e44d3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/retrievers/typeahead/get.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/0c7a1c6ab9c0/schema)