Use this first when the user asks about their niches, or to find a nicheId for use with get_niche_keywords, get_niche_competitors, or get_ranking_juice. Retrieves a paginated list of Niches, newest dive first. Each Niche represents a market segment or product category being tracked. Returns nicheId, heroKeyword, nicheLabel, marketplace (com/uk/de/...), and latestResearchDate per niche, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). Narrow with searchText (label/keyword) or searchAsin (a competitor ASIN) instead of scanning pages; a page holds at most 50 niches, so the full list of a large account needs several calls.

Use this when the user asks about keywords, search terms, or search volume for a niche. Retrieves the master keyword list for the specified Niche — the relevant search terms monitored for ranking and performance metrics. For each keyword, returns search volume, relevancy (numeric score or "Outlier"), and competitor ASIN organic ranks (asinRanks: { ASIN -> rank | null }). Also returns the latestResearchDate.

Use this when the user wants to find the highest-impact words across a niche's keywords, asks about 'keyword roots', or wants to prioritize terms for a listing. Retrieves the keyword lexical roots for the Niche — individual words or word-combinations extracted from the Master Keyword List (e.g. 'bluetooth headphones' yields roots 'bluetooth', 'headphones', 'bluetooth headphones'). Returns roots and normalizedRoots tables, each item with root, frequency (how many keywords contain it), broadSearchVolume (summed search volume of those keywords), and broadSearchVolumeRatio (0-1, relative to the top root), plus the per-keyword breakdowns and latestResearchDate.

Use this for competitor ASINs, product titles, BSR, sales/revenue benchmarks, or niche opportunity scoring. Retrieves the list of Competitors within the specified Niche along with Niche statistics. For the Niche: keyword statistics, opportunity evaluation, benchmark median values, and overall competitor strength assessment. For each Competitor: ASIN, product title, BSR, category and full category tree, sales, revenue, ratings, reviews, price, number of variations, image URL, total Ranking Juice, and ranking data. BSR supports ranking Competitors by sales position within mentioned category. For the Ranking Juice breakdown by title, bullets and description, use get_ranking_juice.

Use this when the user asks 'how do I rank higher', 'what's my ranking juice', or wants listing-optimization guidance. Retrieves the Ranking Juices for each Competitor within the specified Niche. Ranking Juice is DataDive's proprietary metric identifying the key factors driving search-ranking success for each Competitor's listing. Returns currentListing and optimizedListing breakdowns (rankingJuice + per-property contributions: title, bullets, description) plus per-competitor listing scores and the latestResearchDate.

Use this to find a rankRadarId before calling get_rank_radar_data. Filter by nicheId if the user has already identified a niche. Retrieves a paginated list of Rank Radars — keyword-rank trackers monitoring organic and sponsored positions for specific ASINs over time. Each item includes id, status (ACTIVE, PAUSED or ARCHIVED), asin, marketplace, keywordCount, title, imageUrl, and summary metrics: top10KW, top10SV, top50KW, top50SV. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev); a page holds at most 50 Rank Radars, so a large account needs several calls.

Use this to analyze keyword ranking trends over time. Requires startDate and endDate (yyyy-mm-dd), at most 90 days apart. Retrieves historical keyword ranking data for the specified Rank Radar within the date range. Without currentPage and pageSize it returns every active keyword in one result. To read one page instead — faster for large Rank Radars — pass currentPage and/or pageSize (max 100) and continue with currentPage + 1 while hasNext is true. The response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev; total is the Rank Radar's active keyword count. Paused keywords are not included. Each keyword has id, keyword, searchVolume, relevancy, ranks (per-day { date, organicRank, sponsoredRank, impressionRank }), and any highlight annotations. A rank of 101 means the product was not in the top 100 results that day. For PPC metrics use get_rank_radar_ppc_data; for Search Query Performance use get_rank_radar_sqp_data. Use after list_rank_radars to discover a rankRadarId.

Use this when the user asks how shoppers search, click, add to cart and buy for the keywords of a Rank Radar — Amazon's Search Query Performance (SQP) data, from Brand Analytics. Requires startDate and endDate (yyyy-mm-dd), at most 90 days apart; 30 days or less keeps it fast. Each keyword's metrics are aggregated over the range: searchQueryVolume and searchQueryScore; impressions, clicks, cart adds and purchases, each as the total across all sellers (*TotalCount), this ASIN family's count (*AsinCount) and its share (*AsinShare); click, cart-add and purchase rates; and ctr/cvr for the market (*Total) and for this ASIN family (*Asin). numberOfDaysWithData says how many days of the range had SQP data; metrics are null when there is none, which is normal for low-volume keywords, recent dates (Amazon publishes SQP with a delay) and sellers without Brand Analytics. Results are paged by keyword: data holds one page, and the response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev. total is the Rank Radar's active keyword count; to read every keyword, call again with currentPage + 1 while hasNext is true, using pageSize 100 for large Rank Radars. Paused keywords are not included. Each call counts toward API usage and is rate limited (about 60 requests/minute). Use after list_rank_radars to discover a rankRadarId.

Use this when the user asks about advertising (Sponsored Products) performance for the keywords of a Rank Radar. Requires startDate and endDate (yyyy-mm-dd), at most 90 days apart; 30 days or less keeps it fast. Each keyword's metrics are aggregated over the range: sponsoredRank (median; 101 means not in the top 100 sponsored results), impressionRank and impressionRankShare; how many exact, phrase, broad and auto campaigns target it; organicSales, ppcSales, ppcSpend, costPerClicks, clickThroughRate, conversionRate, totalClicks, totalImpressions, totalOrders and acos. Metrics are null or 0 when the seller runs no ads on a keyword. Set includeCampaigns for the per-campaign breakdown. Results are paged by keyword: data holds one page, and the response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev. total is the Rank Radar's active keyword count; to read every keyword, call again with currentPage + 1 while hasNext is true, using pageSize 100 for large Rank Radars. Paused keywords are not included. Each call counts toward API usage and is rate limited (about 60 requests/minute). For the seller's campaigns as a whole, use list_ppc_campaigns. Use after list_rank_radars to discover a rankRadarId.

Use this to start tracking organic and sponsored keyword rankings for an ASIN within a niche. ⚠️ Spends Search Term tokens (cost scales with numberOfKeywords) and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and creates a separate Rank Radar — if a call errors or times out, check list_rank_radars instead of re-calling. The first call previews the creation and may return warnings alongside the cost note — for example that this product family is already tracked by another Rank Radar. Show every warning message to the user verbatim, before asking them to confirm; do not summarise it or decide on their behalf. A warning never blocks creation. Returns the new rankRadarId; read its data later with get_rank_radar_data. Requires asin, numberOfKeywords (min 1), and a nicheId from list_niches.

Use this to start new niche research from a seed ASIN. ⚠️ Spends dive tokens (cost scales with numberOfCompetitors) and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and starts a separate dive — if a call errors or times out, poll get_dive_status (or check list_niches) instead of re-calling. The dive runs asynchronously: this returns immediately with a diveId and an estimatedCompletionDate. Poll get_dive_status with that diveId until it reports success (which carries the new nicheId for use with list_niches, get_niche_keywords, etc.). Requires marketplace, asin, and numberOfCompetitors (min 2).

Use this when the user already knows which products belong in the niche — e.g. they list competitor ASINs, or picked them from search results — and wants niche research on exactly those. Unlike create_niche_dive, which discovers competitors around one seed ASIN, this builds the niche from the given ASINs only (2-200). ⚠️ Spends dive tokens for every ASIN and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and starts a separate dive — if a call errors or times out, poll get_dive_status (or check list_niches) instead of re-calling. Fails without spending tokens when the ASIN count is over the plan's limit, when the account is at its niche limit, or when Amazon product data cannot be found for enough of the ASINs. The dive runs asynchronously: this returns a diveId and an estimatedCompletionDate; poll get_dive_status with the diveId until it reports success, which carries the new nicheId.

Use this to refresh an existing niche's research with current Amazon data, instead of creating a new niche with create_niche_dive. ⚠️ Spends dive tokens (one batch per ASIN dived) and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and starts a separate re-dive — if a call errors or times out, poll get_dive_status instead of re-calling. Two modes: same_competitors re-dives the niche's current competitor set (no other argument needed) and discover finds a fresh set, sized by numberOfCompetitors and steerable with heroAsin / lockedAsins / excludedAsins. Runs asynchronously: returns a diveId and an estimatedCompletionDate — poll get_dive_status with that diveId until it reports success. The niche keeps its nicheId, so existing rank radars and reports follow the refreshed data.

Use this to poll a niche dive started with create_niche_dive, create_niche_dive_from_competitors_list or redive_niche until it finishes. Returns one of three shapes keyed by status: in_progress (with estimatedCompletionDate), success (with the nicheId plus tokensUsed/tokensLeft), or error (with an error message). On success, use the nicheId with list_niches, get_niche_keywords, get_niche_competitors, etc. (for a re-dive it is the same niche you passed in, now carrying refreshed data). Re-poll periodically — dives can take minutes; the estimatedCompletionDate hints at when to check.

Use this to start tracking extra keywords on an existing Rank Radar, instead of creating a new one with create_rank_radar. New keywords are added to the niche and tracked from now on; any matching keyword that was previously paused is resumed. Each newly tracked keyword takes one Daily Tracked Keywords slot, and the call fails if the quota is exhausted — check get_quota first. Reversible with pause_rank_radar_search_terms, which frees the slots again, so it needs no confirm. Returns originBreakdown (where each submitted term ended up) and keywordToRankRadarKeywordIdMap, whose ids are what the pause/resume search-term tools take.

Use this to stop tracking individual keywords on a Rank Radar while keeping the Rank Radar itself active — the way to trim a keyword set the user finds too broad. The DataDive API calls this 'archiving' the search terms; nothing is lost. The paused keywords keep their history and their Daily Tracked Keywords slots are freed for other keywords. Reversible with resume_rank_radar_search_terms, so it needs no confirm. Takes keyword ids, not keyword text: get them from get_rank_radar_data. Safe to repeat: already-paused terms are left unchanged.

Use this to start tracking keywords again that were paused with pause_rank_radar_search_terms. Each resumed keyword takes back one Daily Tracked Keywords slot, and the call fails if the quota is exhausted — check get_quota first. Reversible with pause_rank_radar_search_terms, so it needs no confirm. Takes keyword ids, not keyword text: get them from get_rank_radar_data. Safe to repeat: already-active terms are left unchanged.

Use this to pause tracking on a Rank Radar without losing anything — the action the DataDive API calls 'archiving', so when a user asks to archive a Rank Radar, this is the tool they mean. Tracking stops for all of its keywords and the Daily Tracked Keywords quota they held is freed for other Rank Radars, while the Rank Radar and its ranking history are kept. Fully reversible with resume_rank_radar, so it needs no confirm — prefer it over delete_rank_radar whenever the user may want the data back. Paused Rank Radars show up in list_rank_radars under status: PAUSED — not ARCHIVED, which covers Rank Radars removed with delete_rank_radar. Safe to repeat: pausing an already paused Rank Radar succeeds and changes nothing.

Use this to restart tracking on a Rank Radar that was paused with pause_rank_radar (shown by list_rank_radars under status: PAUSED; a deleted, ARCHIVED one cannot be resumed). Keywords are resumed as far as the available Daily Tracked Keywords quota allows, most relevant first — so with a tight quota only part of the original keyword set comes back; check get_quota first if that matters. Reversible with pause_rank_radar, so it needs no confirm. Fails with a bad-request error when there is no quota left at all. Safe to repeat: resuming an already active Rank Radar changes nothing.

Use this to permanently remove a Rank Radar and all of its keyword ranking history. ⚠️ Cannot be undone — there is no restore endpoint; set confirm: true only after the user approves. It does free the Daily Tracked Keywords quota those keywords held. Deleted Rank Radars are what list_rank_radars returns for status: ARCHIVED. If the user only wants to stop tracking for a while and keep the history — or asks to 'archive' the Rank Radar, which is what the DataDive API calls pausing — use pause_rank_radar instead: it frees the same quota and is reversible with resume_rank_radar.

Use this to permanently remove a niche the user no longer needs. ⚠️ Deletes the niche and everything attached to it — keywords, competitors, all dives and diveboxes — and cannot be undone; the dive tokens already spent on it are NOT refunded. Set confirm: true only after the user approves. A niche used by any Rank Radar cannot be deleted: the call fails with a conflict, so delete or archive those rank radars first (list_rank_radars with the nicheId filter shows them).

Use this to draft an optimised Amazon listing — title, bullets and description — from a niche's keyword research and the seller's current listing. It writes text only: nothing is published to Amazon, and the user still has to paste the result into Seller Central. ⚠️ Spends one AI Copywriter prompt from the quota per call and cannot be undone — set confirm: true only after the user approves. Not safe to retry: each call spends another prompt, so if a call errors or times out, poll get_listing_copy_generation_status instead of re-calling. Runs asynchronously: returns a generationId — poll get_listing_copy_generation_status with it until the status is complete.

Use this to poll a listing-copy draft started with generate_listing_copy until it finishes. Returns one of three shapes keyed by status: generating (still running — poll again in a few seconds), complete (with result, carrying the generated title, bullets, description, itemHighlights and its rankingJuice score), or failed (with an error message). Polling is free — it does not spend another AI Copywriter prompt, so always poll rather than re-calling generate_listing_copy.

Use this when the user asks which Amazon seller accounts are connected, or as the discovery step to find the sellerId and marketplace required by get_asin_inventory_distribution, get_seller_catalog, get_seller_listing_changes, and the alert tools. Returns a paginated list of the organization's connected seller profiles — each item has sellerId, sellerName, marketplace (e.g. "com", "co.uk"), hasAdApi (whether Advertising API credentials are connected), and createdAt — plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Use this when the user wants to browse or search a seller's own Amazon catalog — the products they sell on a given marketplace. Requires a sellerId + marketplace (use list_seller_profiles to discover them). Filter by search (title/brand), brand, and status (Active by default, or all). Returns a paginated list where each item has asin, title, parentAsin, brand, status, imageUrl, and hasVariations, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Use this when the user asks what changed on their Amazon listings — price, content (title/bullets/description), or image edits — for a seller account. Requires a sellerId + marketplace (use list_seller_profiles to discover them). Filter by types, asin/parent ASIN, brand, search, and a startDate/endDate range; sort with sortBy/sortOrder. Set includeCorrelations: true to attach the ranking/conversion impact per change. Returns a paginated list where each item has asin, title, imageUrl, date, type, contentType, description, previousValue, newValue, and (optionally) correlation, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Use this when the user asks about their Sponsored Products campaigns — which campaigns spend the most, which have a high ACOS, how placements (top of search, rest of search, product pages) perform, or which campaigns advertise a given product. Requires a sellerId + marketplace (use list_seller_profiles to discover them). Narrow to one product with asin, or to a variation family with parentAsin (not both). The reporting window defaults to the last 30 days and cannot exceed 90 days. Returns a paginated list where each campaign has campaignId, name, type, state, targetingType, bidStrategy, budget { type, amount, currencyCode }, window totals (impressions, clicks, ctr, cpc, cvr, spend, unitsSold, orders, sales, tosImpressionShare, acos, roas, tacos), asinCount and, unless includePlacements is false, placements; plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). To find the biggest spenders, sort with sortBy: "spend", sortOrder: "DESC" rather than paging through every campaign. Each call counts toward API usage and is rate limited (about 60 requests/minute). For per-keyword ad data of a Rank Radar, use get_rank_radar_ppc_data.

Use this when the user asks about inventory levels, stock by fulfillment center, or where their units are sitting across Amazon's fulfillment network for a specific ASIN. Requires the Amazon sellerId (from list_seller_profiles or the user's DataDive Connections page at https://2.datadive.tools), the marketplace code, and the ASIN. Returns totalSellableUnits and a per-FC distribution array (fc, state, availableStock, availableStockPercentage). lastUpdatedAt may be null when no successful inventory ingestion has occurred in the last 30 days.

Use this to find products that may have lost search visibility. Retrieves a paginated list of indexing-issue alerts across the user's connected Amazon seller accounts — an alert fires when one of their ASINs is no longer indexed for its tracked keywords. By default returns active (unresolved) alerts from the last 30 days; filter by sellerId, marketplace, status, or updatedSince (for incremental polling). Each item includes id, asin, title, imageUrl, isParent, sellerId, marketplace, lastAlertedAt, and resolvedAt. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Use this to find wasted PPC ad spend. Retrieves a paginated list of blind-spend alerts across the user's connected Amazon seller accounts — an alert flags ad spend on customer search terms that produced little or no sales. By default returns active (unresolved) alerts from the last 30 days; filter by sellerId, marketplace, status, or updatedSince (for incremental polling). Each item includes id, asin, title, imageUrl, sellerId, marketplace, lastAlertedAt, resolvedAt, wastedSpend (total ad spend across unresolved terms), totalKeywordCount, unresolvedKeywordCount, and searchTerms — the unresolved wasted-spend search terms, each with term, spend, sales, clicks, cvr (0-1), and impressions. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Use this when the user asks how much quota or how many tokens they have left, or before creating a Niche Dive or Rank Radar to check remaining headroom. Returns current quota usage and capacity for each billable feature — DIVED_ASINS (Dive tokens), RANK_RADAR_KEYWORDS (tracked keywords), PRODUCT_BRIEF_ASINS, and AI_COPYWRITER_PROMPTS — each with used and capacity (null when unlimited / not applicable), plus nextRefreshDate (ISO-8601 timestamp of the next quota reset, or null). Takes no arguments.

Use this when the user asks who consumed tokens, how their quota was spent, or wants an audit of billable activity over a date range. Retrieves a paginated list of billable feature usage logs for the organization — each entry is a token-consumption event (a dive, rank-radar creation, AI copywriter prompt, etc.). Filter by type (billable feature), search (user name/email), and startDate/endDate. Each item includes name, email, qty (tokens consumed), type, action (specific operation), nicheId/nicheName, rankRadarId, and date, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).