Skip to main content
POST
Text Search: Execute Search

​
Authorization

​
string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

​
Headers

​
string
default:"application/json"
required
​
string
default:"application/json"
required
​
string
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

​
string
required
The url-encoded search query.

​
Body

​
string[]
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, including nested field selection for slicing arrays and filtering collections (for example, images[:2].src, variants[sku=ABC].price, metafields[namespace=custom]).
​
string
ULID identifier from the Prepare Search endpoint for optimized search execution. When provided, uses pre-computed embeddings and query expansions.
​
object
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
​
Pagination Object
​
string[]
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:
​
boolean
If the count of each facet value should be calculated
​
boolean
If you want a min/max range for numeric facets such as price.
​
array
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.
​
array
Specify which product variants should be selected by default in the 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_variant field 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)
Example:
Multiple options example (OR logic):
This will select variants with either February OR March birthstone, preferring the first match found.
​
object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
​
object
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.
​
string
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.
​
boolean
default:"false"
When set to true, products with no available variants are excluded from results regardless of the store-level out-of-stock visibility setting. If your store has location-based stock checking configured, the same location rules apply.This is useful when a specific search integration or page requires strict in-stock filtering even though the store default allows out-of-stock products to appear.
​
object
Per-request overrides for response behavior. Currently controls image preload hints emitted in the Link response header. You can disable preloads or narrow the srcset to the breakpoints your storefront uses. You cannot enable preloads when the store has them disabled.Example:

​
Response

​
Array of Objects
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).
​
number
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.
​
number
The current page number.
​
number
The total number of pages. Calculated based on tile count when variant breakouts are enabled.
​
string
A unique request identifier (ULID) for this API call. Use this token to correlate search requests with analytics events via the Beacon API, and to match requests to entries in the Search Inspector.
​
object
If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.
​
object
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.
​
object
​
array of objects
An ordered trace of processing steps the engine performed to produce results for this request. Each entry represents a stage in the search pipeline, recorded in the order it was executed. Use this field to understand how Layers interpreted and transformed your query, which rules and boosts were applied, and why results appear in a particular order.This field is useful for debugging search behavior in development and is also surfaced in the Search Inspector panel.

​
Response headers

Every API response includes the following headers for request tracing and performance optimization:

​
Variant breakouts

When variant breakouts are configured, results may include both product tiles and variant tiles. Each result includes a __typename field to identify the tile type:
​
string
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:
​
number
The parent product ID. Use this to link back to the full product or group variants from the same product.
​
number
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.