get
https://{yourinstance}.makaira.io/search-terms
Returns a paginated list of search terms recorded within a given time range.
Returns a paginated list of search terms recorded within a given time range.
Request
GET /search-terms
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
since | string | 1d | Time range to look back. Accepts values like 1d (1 day), 7d (7 days), 30d (30 days). |
_start | integer | 0 | Offset for pagination. |
_end | integer | 10 | End index for pagination (exclusive). The number of returned items equals _end - _start. |
language | string | — | Filter by shop language (e.g. de, en). If omitted, all languages are returned. |
includeBotTraffic | boolean | false | When true, search terms from detected bot traffic are included. |
hits | boolean | true | When true, returns search terms that produced results. When false, returns search terms with zero results and annotates each entry with a status field from the search term check. |
Headers
| Header | Value |
|---|---|
Authorization | Bearer <token> |
Response
Returns a JSON array of search term objects. The total count of matching items is returned in the X-Total-Count response header.
Response Headers
| Header | Description |
|---|---|
X-Total-Count | Total number of search terms matching the query (before pagination). |
Response Body
Array of objects with the following fields:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the search term record. |
search_phrase | string | The search term entered by the shopper. |
count | integer | Number of times this search term was used within the requested time range. |
status | object | null | Only present when hits=false. Contains the result of a search term check with handled (boolean) and handlers (array) fields. |
Example Response
[
{
"id": "running-shoes",
"search_phrase": "running shoes",
"count": 142,
"status": null
},
{
"id": "winter-jacket",
"search_phrase": "winter jacket",
"count": 87,
"status": null
}
]When hits=false, each item includes a status object:
[
{
"id": "bleu-jens",
"search_phrase": "bleu jens",
"count": 12,
"status": {
"handled": false,
"handlers": []
}
}
]