query_sqp
Amazon SEARCH QUERY PERFORMANCE (Brand Analytics), curated — what shoppers TYPE on Amazon, the whole market's funnel on each query, and your slice of it. ORGANIC demand: this is not ads, and not query_search_terms (that one is what people typed before clicking YOUR ad; this is every seller's behaviour on the query). Answers: which keywords grow or shrink my market, where I lose share, which high-volume queries I am absent from, whether competitors take my brand, do I convert better than the market, am I priced above it. Two vocabularies: market_* = all sellers on that query, your_* = this product. ⏱ FIXED CALENDAR PERIODS: grain is REQUIRED ('week' | 'month'); omit from/to and you get the LATEST COMPLETE period, which is what you almost always want. The response echoes the period actually served: period.from/to are period STARTS (the mart key — read alone they look like one day), and period.covers is the SAME period in calendar DAYS (an SQP week is SUNDAY→Saturday, not an ISO Monday week; a month 1st→last). Weekly runs ~10 days behind, monthly ~7 WEEKS behind, so when crossing with query_metrics / query_advertising / query_search_terms you MUST pass EXACTLY period.covers.from and period.covers.to as their from/to — never 'this month', never period.from/to, and never a weekly series from those tools (their weeks start on Monday and will not line up with SQP weeks). 🔒 HISTORY DEPTH: on a trial plan the response carries dataFloor, an ISO day — NOTHING before it was served, whatever the seller's real history holds, so absence below that day means 'withheld by the plan', never 'no demand'. The field is ABSENT when nothing was withheld. Say so instead of concluding a keyword is new or a market collapsed. 📊 COMPARISON IS A METRIC, not a mode: use search_volume_yoy_pct (month) or search_volume_wow_pct (week) — they are like-for-like, computed only over keywords present in BOTH periods; comparing period totals reads +34% where the truth is -3%. Read comparable_keywords / comparable_share to see how solid it is; the metric is null below the reliability floor. ⚠️ DO NOT SUM market_* VALUES ACROSS ROWS YOURSELF: a query's volume is repeated on every parent ASIN that ranks on it, so adding rows double counts (measured x2.4). The summary block is already de-duplicated — use it. ⚠️ FILTER queryTypes OR YOUR ANSWER IS NOISE: too_broad and long_tail are category demand and dominate any total, so 'my biggest gap' unfiltered returns head terms like 'makeup'. Use ['core','presence','suggested','competitor'] for actionable work, ['core'] for your tight market, ['own_brand'] for brand defence. 🔗 CROSSING WITH PPC: group by keyword and each row carries variants, the spellings that query merges — filter query_advertising/query_search_terms with ALL of them, because 35% of served queries have several spellings and they carry 60% of the volume, so matching one string silently misses real campaigns. The reverse works too: pass your PPC targets into keywords here and they resolve through the same clustering. Metric keys are their OWN universe — not list_metrics keys, not ads keys. 💱 CURRENCY: monetary values are ALWAYS served in the organization's primary currency — the secondary currencies are not supported on this route; currency in the response is the code and currencyNotice, when present, MUST be relayed to the user.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text search over the query wording. | |
| to | No | Window on period STARTS: every complete week/month whose start date is <= to is served (a week starting on `to` is fully included). Omit BOTH from/to to get the latest complete period. | |
| from | No | Window on period STARTS: every complete week/month whose start date is >= from is served. Omit BOTH from/to to get the latest complete period. | |
| skus | No | SKUs — resolved up to their families. | |
| tags | No | "Your Filters" tag IDS from list_tags — a tag NAME is rejected. | |
| grain | Yes | REQUIRED. 'month' for year-over-year, month-over-month and trend work; 'week' for anything recent (10-day lag vs ~7 weeks). | |
| limit | No | Rows per call of an entity grouping, 1 to 1000 (default 50). groupBy 'period' is never cut: the series comes whole, in date order. | |
| reason | No | One sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used. | |
| sortBy | No | SQP metric key to rank rows by (e.g. "search_volume"). Refused with groupBy 'period': the series comes in date order. | |
| groupBy | No | 'keyword' is the main drill-down (and the only grain that returns `variants`); 'parentAsin', 'queryType', 'marketplace', or 'period' for a time series — one row per published week/month of the requested grain, keyed {type:'period', granularity, from, to} (from/to are the SQP period bounds, NOT your from/to). Omit for one total row. | |
| metrics | Yes | SQP metric keys (search_volume, your_impression_share, market_purchases, search_volume_yoy_pct, …) — NOT product or ads keys. Like-for-like variances carry their horizon in the name: _yoy_ and _mom_ at grain month, _wow_ at grain week. | |
| accounts | No | Restrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id. | |
| keywords | No | Exact customer queries — matched through the clustering, so any spelling of the query works (pass your PPC targets here directly). | |
| sortOrder | No | desc (default) = biggest first. | |
| childAsins | No | Child ASINs — resolved UP to their families (a child has no market of its own). | |
| queryTypes | No | How the query relates to the product. READ THE TOOL DESCRIPTION: leaving this open returns category head terms. The cockpit's SQP columns use ['core','presence','suggested','ads_only','low_ctr'] — pass exactly that to match what the seller sees in Nova. | |
| parentAsins | No | Family keys — the grain SQP is reported at. | |
| marketplaces | No | Marketplace IDs. | |
| metricFilters | No | Server-side thresholds (ANDed) — e.g. your_impression_share < 5 AND search_volume > 1000 for the gaps that matter. Needs an entity grouping. |