Text Search: Execute Search
Text Search
Text Search: Execute Search
Execute text-based semantic searches within your product catalog with typo tolerance and query understanding.
POST
Text Search: Execute Search
Authorization
Token-based authentication header in the form of
<YOUR_LAYERS_TOKEN>.Headers
Optional header to identify SDK client requests. Format:
sdk-name/version (e.g., layers-js-sdk/1.0.0). When provided with version >= 1.0.0, the server returns HTTP 425 (Too Early) with a Retry-After header when prepared search data isn’t ready yet, instead of blocking. This enables efficient client-side polling for async search operations.Path Parameters
The url-encoded search query.
Body
Product attributes to include in the response. By default, all attributes are included. Available attributes include:
id, title, handle, body_html, vendor, product_type, tags, images, available, created_at, updated_at, published_at, price_range, options, original_options, metafields, named_tags, calculated, category, featured_media, is_gift_card, has_variants_that_require_components, combined_listing_parent_product_id, combined_listing_role, first_or_matched_variant, and variants. See the Product Schema for detailed descriptions.ULID identifier from the Prepare Search endpoint for optimized search execution. When provided, uses pre-computed embeddings and query expansions.
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
Facets to be included. Accepts both exact facet codes (e.g.,
"vendor", "options.Size") and wildcard patterns (e.g., "options.*", "metafields.product.*").Wildcard patterns expand to all matching attribute codes. For example, "options.*" expands to all option facets like "options.Size" and "options.Color". Wildcards must match at least one attribute code to be valid.Examples:If the count of each facet value should be calculated
If you want a min/max range for numeric facets such as price.
Apply discounts to products, variants, or collections. When provided, price-based sorting and filtering will use discounted prices. See the Discount Entitlements guide for detailed usage.
Specify which product variants should be selected by default in the Multiple options example (OR logic):This will select variants with either February OR March birthstone, preferring the first match found.
first_or_matched_variant field. This is useful for scenarios like defaulting to a specific birthstone option when searching in a jewelry store.Behavior:- Uses OR logic - selects the first variant matching ANY of the specified option values
- Falls back to the first variant by position if no match is found
- Automatically skipped when any option or variant filters are applied (filters take precedence)
- Only affects the
first_or_matched_variantfield in the response - Works with Variant Breakouts - product tiles respect your default selected options, and variant tiles respect non-breakout default selected options (preferring variants that match your preferences within each breakout group, with fallback to position ordering)
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
Contextual information about the customer’s session, behavior, and environment. Automatically collected by the Storefront Pixel; must be manually provided for headless integrations. See Contextual Information for implementation guidance.
Code of the sort order to apply. Use
"relevance" for the default relevance-based ranking, or any custom sort order code configured in your store. Retrieve available sort order codes from the Sort Orders API.When
true, includes detailed timing metrics in the response _meta.timings object for debugging and performance analysis. Only available when using the prepare/execute flow (i.e., when search_id is provided). Timing values are in milliseconds.Response
Semantic Redirects: When a text search query semantically matches a configured redirect term, the response will include a
_meta.redirect object with the redirect URL. In this case, the results array will be empty and totalResults will be 0. Semantic redirects only apply to text search queries (not image or similar product searches).The total number of results. When variant breakouts are enabled, this reflects the count of tiles (both product and variant tiles) rather than just products.
The current page number.
The total number of pages. Calculated based on tile count when variant breakouts are enabled.
The attribution token.
If
includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.If
retrieveFacetCount is true then an object with keys and values of the specified attributes. When variant breakouts are enabled, facet counts reflect tile counts rather than product counts. Empty values and literal "null" strings are automatically excluded from facet results.Variant Breakouts
When variant breakouts are configured for search, results may include both product tiles and variant tiles. Each result includes a__typename field to identify the tile type:
Identifies the type of tile in the results:
"Product"- A standard product tile"Variant"- An individual variant tile from a product with a configured breakout option
Variant Tile Fields
Variant tiles include additional fields to identify the specific variant:The parent product ID. Use this to link back to the full product or group variants from the same product.
The specific variant ID. For variant tiles, this matches the
id field.For variant tiles, the
id field contains the variant ID (not the product ID). The title field is formatted as "{product title} - {option value}" by default (e.g., “Amethyst Ring - Rose Quartz”), but this can be configured per breakout. If the breakout’s “Include Option Value in Title” setting is disabled, the title will be the original product title. See the Variant Breakouts documentation for more details.