Search analytics and rule models

Models for search analytics, queries and rules. Check metrics, rule payloads, filtering data and validation constraints.

Data schemas

Response metadata

AnalyticsMeta · Schema · Search analytics and rule models

periodAnalyticsPeriodData Required: Reporting period and its boundaries.

Example: {"as_of":"2026-01-02T00:00:00Z","days":1,"started_at":"2026-01-01T00:00:00Z"}
request_idStringRequired: Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

Example: "example"

Additional fields: No

Reporting period and its boundaries

AnalyticsPeriodData · Schema · Search analytics and rule models

as_ofStringRequired: Time to which the reported data applies.

format: "date-time"

Example: "2026-01-02T00:00:00Z"
daysIntegerRequired: Reporting period in days.

Example: 1
started_atStringRequired: Start date and time.

format: "date-time"

Example: "2026-01-01T00:00:00Z"

Additional fields: No

List search queries — Response

AnalyticsResponse_list_MetricData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <MetricData > Required: Response example · AnalyticsResponse_list_MetricData__.

Example: [{"clicks":1,"last_seen_at":"2026-01-01T12:00:00Z","query_display":"example","query_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","searches":1,"zero_results":1}]
metaAnalyticsPageMeta AnalyticsMeta Required: Response metadata.

Example: {"pagination":{"has_more":false,"limit":20,"next_cursor":null},"period":{"as_of":"2026-01-02T00:00:00Z","days":1,"started_at":"2026-01-01T00:00:00Z"},"request_id":"example"}

Additional fields: No

List occurrences of a search query — Response

AnalyticsResponse_list_OccurrenceData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <OccurrenceData > Required: Response example · AnalyticsResponse_list_OccurrenceData__.

Example: [{"category_id":"example","category_result_count":1,"currency_code":"PLN","is_zero_results":false,"locale_code":"en","market_id":"example","max_price":"0.00","min_price":"0.00","occurred_at":"2026-01-01T12:00:00Z","page":1,"product_result_count":1,"query_display":"example","request_id":"example","results":[{"clicked":false,"entity_id":"example","entity_type":"product","image_url":"https://example.invalid/product.jpg","number":"example","placement_source":"organic","position":1,"sku":"example","slug":"example","title":"example"}],"sort_key":"example","source":"results"}]
metaAnalyticsPageMeta AnalyticsMeta Required: Response metadata.

Example: {"pagination":{"has_more":false,"limit":20,"next_cursor":null},"period":{"as_of":"2026-01-02T00:00:00Z","days":1,"started_at":"2026-01-01T00:00:00Z"},"request_id":"example"}

Additional fields: No

Get search analytics — Response

AnalyticsResponse_OverviewData_ · Fields, types and constraints of data accepted or returned by the API.

dataOverviewData Required: Response example · OverviewData.

Example: {"click_through_rate":0,"clicked_searches":1,"recent":[{"is_zero_results":false,"locale_code":"en","occurred_at":"2026-01-01T12:00:00Z","query_display":"example","query_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","request_id":"example","result_count":1,"source":"results"}],"searches":1,"zero_result_rate":0,"zero_results":1}
metaAnalyticsPageMeta AnalyticsMeta Required: Response metadata.

Example: {"period":{"as_of":"2026-01-02T00:00:00Z","days":1,"started_at":"2026-01-01T00:00:00Z"},"request_id":"example"}

Additional fields: No

List search rules — Response

ApiResponse_list_RuleSummaryData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <RuleSummaryData > Required: Response example · ApiResponse_list_RuleSummaryData__.

Example: [{"created_at":"2026-01-01T12:00:00Z","enabled":true,"id":"example","is_available":true,"market_scope":"all","name":"Example","updated_at":"2026-01-01T12:00:00Z","version":1}]
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

Get a search rule — Response

ApiResponse_RuleDetailData_ · Fields, types and constraints of data accepted or returned by the API.

dataRuleDetailData Required: Response example · RuleDetailData.

Example: {"category_ids":["example"],"created_at":"2026-01-01T12:00:00Z","enabled":true,"id":"example","is_available":true,"market_ids":["example"],"market_scope":"all","name":"Example","phrase_groups":[{"locale":"en","phrases":["example"]}],"product_ids":["example"],"updated_at":"2026-01-01T12:00:00Z","version":1}
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","request_id":"example"}

Additional fields: No

List search queries — Response

MetricData · Fields, types and constraints of data accepted or returned by the API.

clicksIntegerRequired: Number of clicks.

Example: 1
last_seen_atStringRequired: Most recent occurrence time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"
query_displayStringRequired: Search phrase displayed to an administrator.

Example: "example"
query_hashStringRequired: Stable identifier of the grouped search phrase.

Example: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
searchesIntegerRequired: Number of searches.

Example: 1
zero_resultsIntegerRequired: Number of searches with no results.

Example: 1

Additional fields: No

List occurrences of a search query — Response

OccurrenceData · Fields, types and constraints of data accepted or returned by the API.

category_idString nullRequired

Category identifier.

Example: "example"

category_result_countIntegerRequired

Number of category results.

Example: 1

currency_codeStringRequired

Currency code.

Example: "PLN"

is_zero_resultsBooleanRequired

Whether the search returned no results.

Example: false

locale_codeStringRequired

Language code.

Example: "en"

market_idStringRequired

Market identifier returned by the context endpoint.

Example: "example"

max_priceString nullRequired

Maximum price in the reported range.

Example: "0.00"

min_priceString nullRequired

Minimum price in the reported range.

Example: "0.00"

occurred_atStringRequired

Event date and time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

pageIntegerRequired

CMS page information.

Example: 1

product_result_countIntegerRequired

Number of product search results.

Example: 1

query_displayStringRequired

Search phrase displayed to an administrator.

Example: "example"

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

Example: "example"

resultsArray <ResultSnapshotData > nullRequired

Recorded search results.

Example:

[{"clicked":false,"entity_id":"example","entity_type":"product","image_url":"https://example.invalid/product.jpg","number":"example","placement_source":"organic","position":1,"sku":"example","slug":"example","title":"example"}]

sort_keyStringRequired

Ordering key.

Example: "example"

sourceStringRequired

Source of the recorded activity.

Constraints

enum: ["results", "autocomplete"]

Example: "results"

Additional fields: No

Get search analytics — Response

OverviewData · Fields, types and constraints of data accepted or returned by the API.

click_through_rateNumberRequired: Click-through rate for the selected search data.

Example: 0
clicked_searchesIntegerRequired: Number of searches with a click.

Example: 1
recentArray <RecentSearchData > Required: Recent search information.

Example: [{"is_zero_results":false,"locale_code":"en","occurred_at":"2026-01-01T12:00:00Z","query_display":"example","query_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","request_id":"example","result_count":1,"source":"results"}]
searchesIntegerRequired: Number of searches.

Example: 1
zero_result_rateNumberRequired: Share of searches that returned no results.

Example: 0
zero_resultsIntegerRequired: Number of searches with no results.

Example: 1

Additional fields: No

Sort order selected for the results

QueryMetricSort · Fields, types and constraints of data accepted or returned by the API.

String

Constraints

enum: ["last_seen_desc", "last_seen_asc", "searches_desc", "searches_asc", "clicks_desc", "clicks_asc"]

Additional fields: Yes

Recent search information

RecentSearchData · Schema · Search analytics and rule models

is_zero_resultsBooleanRequired

Whether the search returned no results.

Example: false

locale_codeStringRequired

Language code.

Example: "en"

occurred_atStringRequired

Event date and time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

query_displayStringRequired

Search phrase displayed to an administrator.

Example: "example"

query_hashStringRequired

Stable identifier of the grouped search phrase.

Example: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

Example: "example"

result_countIntegerRequired

Number of search results.

Example: 1

sourceStringRequired

Source of the recorded activity.

Constraints

enum: ["results", "autocomplete"]

Example: "results"

Additional fields: No

Recorded search results

ResultSnapshotData · Schema · Search analytics and rule models

clickedBooleanRequired

Whether the result was clicked.

Example: false

entity_idStringRequired

Identifier of the referenced entity.

Example: "example"

entity_typeStringRequired

Type of the referenced entity.

Constraints

enum: ["product", "category"]

Example: "product"

image_urlString nullRequired

Image URL.

Example: "https://example.invalid/product.jpg"

numberString nullRequired

Human-facing order or request number.

Example: "example"

placement_sourceStringRequired

Source from which the order was placed.

Constraints

enum: ["organic", "merchandising"]

Example: "organic"

positionIntegerRequired

Position in the ordered collection.

Example: 1

skuStringRequired

Stock keeping unit code.

Example: "example"

slugStringRequired

URL path segment in the selected language.

Example: "example"

titleStringRequired

Title in the selected language.

Example: "example"

Additional fields: No

Create a search rule — Request body

RuleCreate · Fields, types and constraints of data accepted or returned by the API.

category_idsArray <String> Optional

Identifiers of related categories.

maxItems: 100

Array:minLength: 1maxLength: 63

enabledBooleanOptional

Whether this setting is enabled.

Default: false

market_idsArray <String> Optional

Identifiers of selected markets.

maxItems: 1000

Array:minLength: 1maxLength: 63

market_scopeStringOptional

Whether the resource applies to all or selected markets.

Constraints

enum: ["all", "selected"]

nameStringRequired

Resource name in the relevant context.

minLength: 1maxLength: 160

Example: "Example"

phrasesArray <String> Required

Phrases used by the search rule.

minItems: 1maxItems: 20

Array:minLength: 1maxLength: 255

Example: ["example"]

product_idsArray <String> Optional

Identifiers of related products.

maxItems: 100

Array:minLength: 1maxLength: 63

Example: ["example"]

Additional fields: No

Get a search rule — Response

RuleDetailData · Fields, types and constraints of data accepted or returned by the API.

category_idsArray <String> Required

Identifiers of related categories.

Example: ["example"]

created_atStringRequired

Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

enabledBooleanRequired

Whether this setting is enabled.

Example: true

idStringRequired

Resource identifier; preserve it as returned. (RuleDetailData).

Example: "example"

is_availableBooleanRequired

Whether the item is available in this context.

Example: true

market_idsArray <String> Required

Identifiers of selected markets.

Example: ["example"]

market_scopeStringRequired

Whether the resource applies to all or selected markets.

Constraints

enum: ["all", "selected"]

Example: "all"

nameStringRequired

Resource name in the relevant context.

Example: "Example"

phrase_groupsArray <RulePhraseGroupData > Required

Groups of search-rule phrases.

Example: [{"locale":"en","phrases":["example"]}]

product_idsArray <String> Required

Identifiers of related products.

Example: ["example"]

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

Groups of search-rule phrases

RulePhraseGroupData · Schema · Search analytics and rule models

localeStringRequired: Language selected for this request.

Example: "en"
phrasesArray <String> Required: Phrases used by the search rule.

Example: ["example"]

Additional fields: No

List search rules — Response

RuleSummaryData · Fields, types and constraints of data accepted or returned by the API.

created_atStringRequired

Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

enabledBooleanRequired

Whether this setting is enabled.

Example: true

idStringRequired

Resource identifier; preserve it as returned. (RuleSummaryData).

Example: "example"

is_availableBooleanRequired

Whether the item is available in this context.

Example: true

market_scopeStringRequired

Whether the resource applies to all or selected markets.

Constraints

enum: ["all", "selected"]

Example: "all"

nameStringRequired

Resource name in the relevant context.

Example: "Example"

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

Update a search rule — Request body

RuleUpdate · Fields, types and constraints of data accepted or returned by the API.

category_idsArray <String> Optional

Identifiers of related categories.

maxItems: 100

Array:minLength: 1maxLength: 63

enabledBooleanOptional

Whether this setting is enabled.

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 2147483647

Example: 1

market_idsArray <String> Optional

Identifiers of selected markets.

maxItems: 1000

Array:minLength: 1maxLength: 63

market_scopeStringOptional

Whether the resource applies to all or selected markets.

Constraints

enum: ["all", "selected"]

nameStringOptional

Resource name in the relevant context.

minLength: 1maxLength: 160

Example: "Example"

phrasesArray <String> Optional

Phrases used by the search rule.

maxItems: 20

Array:minLength: 1maxLength: 255

product_idsArray <String> Optional

Identifiers of related products.

maxItems: 100

Array:minLength: 1maxLength: 63

Additional fields: No

Filter selecting searches with or without zero-result occurrences

ZeroResultScope · Fields, types and constraints of data accepted or returned by the API.

String

Constraints

enum: ["all", "has_zero_results", "no_zero_results"]

Additional fields: Yes