Typeahead

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.

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"

Response

{
  "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.

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.

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.

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.

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.

Search Widget for the prebuilt UI components
Retrievers for running the search itself

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Parameters

Reading the response

​Parameters

​Reading the response

​Related

Parameters

Reading the response

Related