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. See the Search API Optimization Guide.
Parameters to fine-tune the search results.
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.
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
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 the ‘semantic-redirects’ feature flag is enabled and 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.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.Product Score Fields
When search results are returned, each product may include scoring information that explains how the result was ranked:The combined relevance score for the product, calculated from both textual and visual similarity. This score is normalized between 0 and 1, where higher values indicate greater relevance to the search query.
An array of objects detailing how each component of the search query contributed to the product’s final score. Each contribution includes:
type: Either “text” or “image” indicating the type of similarity matchquery_label: The specific query term or expansion that contributed to the scorenormalized_score: The normalized contribution value (0-1)similarity_score: The raw similarity score before normalization