A search profile is a saved recipe for one search box: which fields a query looks in and how much each counts, how forgiving it is about typos, which facets and sort orders it offers, which filters always apply and what each hit returns. An index can hold up to 50 profiles, for example one for the storefront search page and one for a B2B catalog.
Each profile has a profile key, 16 URL-safe characters that never change. The storefront sends searches to this key with only the query, filters, sort and page; everything else comes from the profile. A saved change applies to the very next search.
Only organization owners and admins can create and change profiles. Other members can open a profile and look at its settings.
The profile editor with a live preview of the saved and the draft settings
Advanced: JSON shows the same profile as JSON, the way the API takes it. Back to blocks returns to the blocks. Discard drops your unsaved changes.
The Search profiles list shows each profile with its key under the name, and chips for its fields, its facets and its default sort. The Basics block of a saved profile shows the key too, with a Copy button. Give this key to whoever builds the storefront search.
The profile key sits under the profile name
To check a profile against real searches after you save it, use the playground.
Open the row menu (⋯) next to Edit in the list:
/v1/projects/:projectId/indices/:indexId/profilesProject member or any secret keyPOST/v1/projects/:projectId/indices/:indexId/profilesProject admin or a full-access secret keyPUT/v1/projects/:projectId/indices/:indexId/profiles/:profileIdProject admin or a full-access secret keyDELETE/v1/projects/:projectId/indices/:indexId/profiles/:profileIdProject admin or a full-access secret keyThe profile is plain JSON, the same as in the editor's JSON view, and its key comes back as profileKey. The storefront calls POST /v1/search/<profileKey>, see the Search API. PUT replaces the whole profile, so send every setting you want to keep. A save checks the profile against the index mapping: a field must exist and carry the flag its use needs (searchable, facetable, filterable, sortable or returnable), or the API answers 400 PROFILE_INVALID with one issue per field. From an AI agent, the MCP tool upsert_profile creates or changes a profile.
stringValues 1 to 100 charactersThe name you and your team know the profile by. It shows in the cabinet; shoppers never see it.
409 PROFILE_NAME_TAKEN.field → weightValues weights above 0, up to 100; at least one fieldThe fields a query looks in, each with a weight. A match in a field with weight 3 counts three times as much as a match in a field with weight 1. Only searchable fields can be listed.
all | any | allWordsDefault allall returns a product only when every word of the query matches in the same field. any is happy with one word. allWords needs every word too, but each word may match in a different field. all gives precise results for short queries. any returns more products and ranks those that match more words higher.
all, every word has to be found in the same field. "acme mailer" matches a title that holds both words, but not a product whose brand is Acme and whose title only says mailer. allWords matches that product, because "acme" is found in the brand and "mailer" in the title.allWords when your catalog splits words across fields, for example a size in the title and the product type in the description. Every word must still match, so it returns far fewer loose hits than any.allWords on a field that splits numbers, a query word like "300x200" also finds "300x200x150mm". The other two modes look for "300x200" as one word.allWords, a query of five or more words still matches when one word is missing. Pasted product titles often hold one word the catalog spells differently.all. Long natural-language queries are the first to stop matching.numberDefault 2Values 0 to 100; 0 turns it offAn extra boost for products where the query's words appear next to each other, in order. It only lifts products that already match; it never adds new ones.
AUTO | 0 | 1 | 2Default AUTOHow many letters may differ between a query word and a word in a product. AUTO allows none for words of one or two letters, one typo for words of three to five letters and two for longer words. 0 turns typo tolerance off.
AUTO for most catalogs. A fixed 2 lets short words match far too much: two changed letters turn a three-letter word into almost any other.0 for catalogs searched mostly by codes, where a single changed character is a different product.numberDefault 1Values 0 to 10How many letters at the start of a word must be typed exactly before typos are allowed. With 1, "lamp" can match "lump" but not "damp".
booleanDefault trueWhen a search finds nothing, the engine looks for a corrected spelling of the query among the words in your products. The response returns it as correctedQuery, so the storefront can show "Did you mean …?".
booleanDefault trueWith this on, a search that finds nothing is run once more with the corrected query, and the response returns those results with correctedQuery set. Off, the response stays empty and only carries the suggestion.
list of facetsDefault the index facetsValues up to 50The filter panels next to the results, in order. Leave the setting out and the profile shows the index facets, which you manage once on the index's Facets page. In the Facets block, Customize for this profile gives the profile its own list, and Use the index facets goes back. Set it, even to an empty list, and this profile shows its own facets instead.
A facet has a type and a facetable field, and an optional label:
terms: the field's values with product counts; limit 1 to 500 (default 20), order count or key.range: buckets you define with from and to; from is included and to is not. Up to 50 buckets, numeric fields only.stats: the lowest and highest value in the results, for a price slider. Numeric fields only.hierarchy: a category tree that shows the children of the deepest selected category; limit 1 to 500 (default 50). Hierarchy fields only.booleanDefault trueLeaves out facets with nothing to pick for the current search. A facet the request already filters on stays even when it is empty, so the shopper can still see and clear the selection.
list of sortsDefault ["_relevance"]Values 1 to 50 optionsThe sort orders a shopper can pick. Each option is up to 10 clauses joined by commas and applied in order: _relevance (best match first) or field:asc / field:desc on a sortable field, for example price:asc or inStock:desc,_relevance. A field may appear once per option. A request asking for a sort that is not in this list answers 400 SORT_NOT_ALLOWED.
_relevance in the list. Without it, a shopper who picked "price, low to high" cannot get back to best matches._relevance at the end yourself.sortDefault _relevanceThe sort used when a request does not ask for one. It must be one of the sort options, or the save fails.
_relevance. A category page with an empty query is a good place for a field sort such as newest first.list of sort clausesDefault []Values up to 10 clausesSort clauses that lead every search, before the default or the requested sort, such as inStock:desc to show products in stock first. A clause of the chosen sort on the same field is dropped, since it would change nothing after the pinned one.
field → filterDefault {}Filters every search gets. A product shows up only when it matches all of them, and the storefront cannot lift them. A filter is a value, a list of values (any of them), a range {"gte": 10, "lt": 50}, {"exists": true} or category nodes {"terms": ["Boxes>Mailers"]}, on a filterable or facetable field.
{"inStock": true} for a shop that never shows sold-out products.field → filterDefault {}Products that match any of these never show up, whatever the request asks for. They take the same filter forms as always-on filters.
list of fieldsDefault []Values up to 100Fields a request may filter on besides the facet fields. A request filtering on any other field answers 400 FILTER_NOT_ALLOWED, which keeps storefront requests from filtering on fields you did not mean to expose.
currency or a visibility flag.list of fieldsDefault every returnable fieldValues up to 200The fields each hit returns. Leave it out and a hit carries every returnable field of the mapping.
numberDefault 24Values 1 to 1000How many hits a page holds when the request does not say. It cannot be higher than the most a request may ask for.
numberDefault 100Values 1 to 1000The largest perPage a request may send; above it the API answers 400 PER_PAGE_TOO_LARGE. Independently, a page must start within the first 10,000 results.
Search API
Try a search in the playground, then the search request and response for developers, with every filter form, sorting, paging, highlighting and the inline profile.
Facets
The filter panels next to the results, the four facet types, index facets and profile facets, and how a shopper's clicks change the counts.