Menu

Analytics

Search analytics reports.

1 endpoint.

GET /v1/stats/{report}

GET/v1/stats/{report}

Search analytics reports

Needs a key or a dashboard session

Add `format=csv` for a CSV download of the same rows (columns = the report's row fields).

Parameters

Name	In	Type	Required	Description
`report`	`path`	`"overview" \| "top_queries" \| "zero_results" \| "low_ctr" \| "ctr_by_position" \| "conversions" \| "by_language" \| "by_device" \| "assistant"`	yes
`from`	`query`	`string (date) \| null`	no
`to`	`query`	`string (date) \| null`	no
`lang`	`query`	`string`	no	default "all" · pattern ^(all\|[a-z]{2})$
`device`	`query`	`"all" \| "desktop" \| "mobile" \| "tablet"`	no	default "all"
`limit`	`query`	`integer`	no	default 50 · min 1 · max 200
`format`	`query`	`"json" \| "csv"`	no	default "json"

Responses

200Successful ResponseOverviewStats | TopQueriesStats | ZeroResultsStats | LowCtrStats | CtrByPositionStats | ConversionsStats | ByLanguageStats | ByDeviceStats | AssistantStats

Data shapes on this page

OverviewStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"overview"`	yes
`rows`	`OverviewRow[]`	no

StatsTotals

Name	Type	Required	Description
`searches`	`integer`	no	default 0
`suggests`	`integer`	no	Never billed.default 0
`clicks`	`integer`	no	default 0
`ctr`	`number`	no	default 0
`zero_result_rate`	`number`	no	default 0
`add_to_carts`	`integer`	no	default 0
`orders`	`integer`	no	default 0
`conversion_rate`	`number`	no	Searches followed by an order / searches.default 0

OverviewRow

Name	Type	Required	Description
`day`	`string (date)`	yes
`searches`	`integer`	yes
`suggests`	`integer`	yes
`zero_results`	`integer`	yes
`clicks`	`integer`	yes
`ctr`	`number`	yes
`add_to_carts`	`integer`	yes
`orders`	`integer`	yes

TopQueriesStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"top_queries"`	yes
`rows`	`TopQueryRow[]`	no

TopQueryRow

Name	Type	Required	Description
`query`	`string`	yes	Normalized query text.
`searches`	`integer`	yes
`clicks`	`integer`	yes
`ctr`	`number`	yes
`zero_result_rate`	`number`	yes
`avg_click_position`	`number \| null`	no

ZeroResultsStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"zero_results"`	yes
`rows`	`ZeroResultRow[]`	no

ZeroResultRow

Name	Type	Required	Description
`query`	`string`	yes
`searches`	`integer`	yes
`last_seen`	`string (date)`	yes
`suggestion`	`string \| null`	no	A synonym suggestion id or did-you-mean text, if any.

LowCtrStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"low_ctr"`	yes
`rows`	`LowCtrRow[]`	no

LowCtrRow

Name	Type	Required	Description
`query`	`string`	yes
`searches`	`integer`	yes
`clicks`	`integer`	yes
`ctr`	`number`	yes

CtrByPositionStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"ctr_by_position"`	yes
`rows`	`CtrByPositionRow[]`	no

CtrByPositionRow

Name	Type	Required	Description
`position`	`integer`	yes	min 1
`impressions`	`integer`	yes
`clicks`	`integer`	yes
`ctr`	`number`	yes

ConversionsStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"conversions"`	yes
`rows`	`ConversionRow[]`	no

ConversionRow

Name	Type	Required	Description
`query`	`string`	yes
`searches`	`integer`	yes
`clicks`	`integer`	yes
`add_to_carts`	`integer`	yes
`orders`	`integer`	yes
`conversion_rate`	`number`	yes
`revenue`	`string`	yes	In `currency`, from order events.
`currency`	`string`	yes

ByLanguageStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"by_language"`	yes
`rows`	`SegmentRow[]`	no

SegmentRow

Name	Type	Required	Description
`segment`	`string`	yes	by_language: a locale code; by_device: desktop \| mobile \| tablet \| unknown.
`searches`	`integer`	yes
`share`	`number`	yes	This segment's share of all searches.
`clicks`	`integer`	yes
`ctr`	`number`	yes
`zero_result_rate`	`number`	yes
`conversion_rate`	`number`	yes

ByDeviceStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"by_device"`	yes
`rows`	`SegmentRow[]`	no

AssistantStats

Name	Type	Required	Description
`date_from`	`string (date)`	yes
`date_to`	`string (date)`	yes
`totals`	`StatsTotals`	no
`report`	`"assistant"`	yes
`rows`	`AssistantRow[]`	no

AssistantRow

Name	Type	Required	Description
`day`	`string (date)`	yes
`conversations`	`integer`	yes
`messages`	`integer`	yes
`products_shown`	`integer`	yes
`product_clicks`	`integer`	yes
`handovers`	`integer`	yes
`conversion_proxy`	`number`	yes	Conversations with a product click / conversations.
`cost_usd`	`string`	yes