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), spaces or labels (ids from list_spaces / list_labels) instead of scanning pages; each niche lists the ids of its spaces and labels. A page holds at most 50 niches, so the full list of a large account needs several calls.

Use this first when the user asks about their Fast Keywords runs, or to find a fastKeywordsId for get_fast_keywords, get_fast_keywords_keywords or refresh_fast_keywords. Fast Keywords finds the keywords a product ranks for from just an ASIN, in minutes and for 1 Dive token, without a full niche dive. Lists the runs of the whole organization, newest request first: fastKeywordsId, asin, parentAsin, marketplace, status (in-progress, success or failed), title, brand, price, keywordCount, totalSearchVolume, top10OrganicRankCount, rootCount, lastRefreshedAt and requestedAt, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). Narrow with search or marketplace.

Use this to poll a Fast Keywords run started with run_fast_keywords or refresh_fast_keywords, and to read its result. While status is in-progress, wait a few seconds and call again; stop at success or failed. On failed, failureReason and failureMessage say why (safe to show to the user). On success it returns the product (title, brand, price, imageUrl), its variations, keywordCount, lastRefreshedAt, the top keyword roots by search volume (root, aggregateSearchVolume, medianOrganicRank, keywordCount, and a sample of its keywords; totalRoots is how many there are) and the top 10 competitors. insufficientKeywordData: true means the run succeeded but found too few keywords to be useful. The keyword rows themselves are in get_fast_keywords_keywords.

Use this to read the keywords of a finished Fast Keywords run (check status is success with get_fast_keywords first). Returns keyword, searchVolume, organicRank and sponsoredRank per keyword, highest search volume first, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). A page holds at most 100 keywords; keep requesting the next page while hasNext is true.

Use this first when the user talks about Spaces, or to find the ids that add_niche_spaces, remove_niche_spaces and the spaces filter of list_niches and list_rank_radars take. Returns the Spaces as a tree: each node has id, name, path (names from the root joined with /), parentId and children. An MCP user sees only the Spaces they have rights on, so a Space that is missing from the tree is one they cannot use. Niches carry the ids of their Spaces in spaces / labels on list_niches.

Use this first when the user talks about labels, or to find the ids that add_niche_labels, remove_niche_labels and the labels filter of list_niches and list_rank_radars take. Returns the labels as a tree: each node has id, name, path (names from the root joined with /), parentId and children. Labels carry no access rights, so every label of the organization is listed. Niches carry the ids of their labels in spaces / labels on list_niches.

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 }), plus origin: mkl (found by the dive), manual (added by hand with add_niche_keywords), outlier / residue (moved in from those lists). Only manual, outlier and residue keywords can be taken out with remove_niche_keywords. Keywords hidden by the niche's keyword exclusions are not listed; see list_keyword_exclusions. Also returns the latestResearchDate.

Use this to see which keywords are hidden from a niche's Master Keyword List, e.g. when a keyword the user expects is missing from get_niche_keywords. Returns the same lists the DataDive web app shows, oldest first: exact — each entry hides the one keyword that matches it exactly, with that keyword's searchVolume (0 when the niche has no such keyword); phrase — each entry hides every keyword that contains the phrase, with excludedKeywordsCount and the total searchVolume of the keywords it hides (not counting ones already excluded exactly). Exclusions hide keywords wherever they come from: the dive, the Outliers and Residue lists, and hand-added ones. Change them with add_keyword_exclusions and remove_keyword_exclusions.

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, or by spaces / labels (ids from list_spaces / list_labels), which match through the Rank Radar's 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 highlights — the user tags on this keyword. Each highlights entry is the same object list_rank_radar_tags returns (id, title, color, description, startAt, endAt, type, krtId, krtKeywordId); its id is the tagId the tag-management tools take. 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 find a tagId before calling update_rank_radar_tag, delete_rank_radar_tag, add_rank_radar_tag_search_terms or remove_rank_radar_tag_search_terms. Returns the user tags ("highlights") on the specified Rank Radar, ordered by title (case-insensitive, ascending). Each row carries id, title, color, description, startAt, endAt, createdAt, and keywordCount — the number of Rank Radar keywords this tag is applied to. The system "paused" tag (the one the quota pauser writes with a reserved colour) is not listed and cannot be addressed from these tools. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev); a page holds at most 50 tags.

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 find the keywords a product ranks for from just its ASIN — in minutes, without a full niche dive. ⚠️ Spends 1 Dive token and cannot be undone. The first call checks eligibility and the Dive token balance, spends nothing and returns confirmation_required with tokenCost and hasEnoughTokens; call again with confirm: true only after the user approves. Not safe to retry: each confirmed call spends a token — if it errors or times out, check list_fast_keywords instead of re-calling. Returns fastKeywordsId, requestId, status and estimatedCompletionDate. Poll get_fast_keywords with the fastKeywordsId until status is success (right away when a fresh result for the same product already exists), then read the keywords with get_fast_keywords_keywords. To follow up with a full niche dive for the same product, pass the requestId to create_niche_dive as fastKeywordsRequestId. Run it again later with refresh_fast_keywords.

Use this to re-run an existing Fast Keywords result with current data. ⚠️ Spends 1 Dive token and cannot be undone. The first call checks eligibility and the Dive token balance, spends nothing and returns confirmation_required with tokenCost and hasEnoughTokens; call again with confirm: true only after the user approves. A result can be refreshed once every 24 hours, and not while a run is going: then the call fails with a message that says when it is refreshable again (or to poll get_fast_keywords), and nothing is charged. Not safe to retry after an error or timeout — check get_fast_keywords instead. Returns fastKeywordsId, requestId, status and estimatedCompletionDate; poll get_fast_keywords until status is success.

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). After a Fast Keywords run for the same product, pass its requestId as fastKeywordsRequestId to link the dive to it.

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, or the re-dive add_niche_keywords started on a stale 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 add keywords to a niche's Master Keyword List (MKL): the user's own search terms, or keywords from the niche's Outliers or Residue lists. Free while the niche is fresh (dived in the last 24 hours, or a dive is running): the first call adds the keywords at once and they are readable with get_niche_keywords. On a stale niche, any keyword new to the niche makes the add re-dive the whole niche with its current competitors, which spends one Dive token per competitor. The first call then saves and spends nothing and returns confirmation_required with tokenCost; after the user approves, call again with confirm: true and maxTokensUsed set to that tokenCost. Keywords moved in from Outliers or Residue never cost anything. Returns originBreakdown (alreadyInMkl, takenFromOutliers, takenFromResidue, addedManually) and tokensUsed. When refresh is present a re-dive is running: poll get_dive_status with refresh.diveId; the addedManually keywords show in the MKL once it succeeds. A confirmed call is not safe to retry: if it errors or times out, poll get_dive_status or re-read get_niche_keywords instead of re-calling. Limited to 2 calls per minute per niche, so batch keywords into one call. Undo with remove_niche_keywords. A keyword hidden by the niche's keyword exclusions stays hidden after an add: check list_keyword_exclusions and remove the exclusion with remove_keyword_exclusions first.

Use this to undo add_niche_keywords: take keywords back out of a niche's Master Keyword List (MKL). Only keywords that were added to the MKL can be removed — get_niche_keywords shows each keyword's origin. What happens depends on that origin, and the response reports it per keyword: removedManual — added by hand (manual), deleted from the niche; sentBackToOutliers / sentBackToResidue — moved in from those lists (outlier / residue), listed there again with their data kept; notRemovable — found by the dive itself (mkl) or not in the niche, left unchanged. To hide a keyword the dive found, use add_keyword_exclusions instead. Free, and safe to repeat: a keyword already removed comes back under notRemovable. Adding a hand-added keyword back later re-dives the niche and costs Dive tokens if the niche is stale by then. Limited to 2 calls per minute per niche.

Use this to hide irrelevant keywords from a niche's Master Keyword List — e.g. other brands, wrong product types. exact entries hide the one keyword that matches exactly; phrase entries hide every keyword containing the phrase, so prefer exact unless the user wants a whole family of keywords gone. The excluded keywords drop out of get_niche_keywords at once, wherever they come from: the dive, Outliers, Residue, or ones added with add_niche_keywords. Nothing is deleted: remove_keyword_exclusions brings them back. Only the exclusions change — every other niche setting is kept. Send 1–100 entries in total across exact and phrase; a niche can hold at most 1000 exclusions. Free, no tokens, and safe to repeat: entries already excluded come back under unchanged. Returns added, unchanged and the full exact / phrase lists after the change. Limited to 30 calls per minute per niche, so batch entries into one call.

Use this to undo add_keyword_exclusions, so the keywords an exclusion hid show in the niche's Master Keyword List (get_niche_keywords) again. Pass the entries exactly as list_keyword_exclusions shows them, exact and phrase separately: removing a phrase does not touch an exact entry for the same text, and a keyword also hidden by another remaining exclusion stays hidden. Only the exclusions change — every other niche setting is kept. Send 1–100 entries in total across exact and phrase. Free, and safe to repeat: entries that are not excluded come back under unchanged. Returns removed, unchanged and the full exact / phrase lists after the change. Limited to 30 calls per minute per niche.

Use this to put a niche in one or more Spaces (ids from list_spaces). A Space controls who can see the niche, so adding or removing one changes access. Returns added and alreadyPresent. Undo with remove_niche_spaces. Only the organization owner or a team admin can change a niche's Spaces and labels; anyone else is refused with a 403 (INSUFFICIENT_ROLE), so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Use this to take a niche out of one or more Spaces (ids from list_spaces). A Space controls who can see the niche, so adding or removing one changes access. Returns removed and notPresent. Undo with add_niche_spaces. Only the organization owner or a team admin can change a niche's Spaces and labels; anyone else is refused with a 403 (INSUFFICIENT_ROLE), so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Use this to put a niche in one or more labels (ids from list_labels). Returns added and alreadyPresent. Undo with remove_niche_labels. Only the organization owner or a team admin can change a niche's Spaces and labels; anyone else is refused with a 403 (INSUFFICIENT_ROLE), so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Use this to take a niche out of one or more labels (ids from list_labels). Returns removed and notPresent. Undo with add_niche_labels. Only the organization owner or a team admin can change a niche's Spaces and labels; anyone else is refused with a 403 (INSUFFICIENT_ROLE), so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

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 create a new user tag ("highlight") on a Rank Radar — the way the UI marks a window on the ranking chart. Writing a tag costs nothing and is reversible with delete_rank_radar_tag, so no confirmation is required. Returns the new tag row (id, title, color, description, startAt, endAt, keywordCount, createdAt); the id is the tagId the other tag tools take. If the title clashes with an existing tag on this Rank Radar, the API answers 409 { error: 'TAG_TITLE_EXISTS', existingTagId } so callers can reuse the existing tag without a follow-up list_rank_radar_tags. The reserved colour #EB5757 is rejected with 400. Pass rankRadarKeywordIds to tag a batch of keywords in the same call; otherwise create the tag and attach keywords later with add_rank_radar_tag_search_terms.

Use this to change a tag's title, colour, description, or date window. Partial update: only the fields you pass are modified, the rest are left as they are. The system "paused" tag (reserved colour, written by the quota pauser) cannot be addressed from here — the API answers 404. Writing a tag costs nothing and is reversible, so no confirmation is required. Returns the updated tag row. Title clashes return 409 { error: 'TAG_TITLE_EXISTS', existingTagId }; the reserved colour returns 400; and endAt < startAt returns 400 (for whichever side the body omits, the comparison uses the stored value).

Use this to tag a batch of keywords on a Rank Radar — the same relation create_rank_radar_tag writes when rankRadarKeywordIds is passed on creation, so this is how you keep extending a tag's keyword set over time. Reversible with remove_rank_radar_tag_search_terms, so no confirmation is required. Idempotent: already-attached keywords are left unchanged, so re-sending the same ids after a timeout is safe. Up to 1000 ids per call — split larger batches into multiple calls. The system "paused" tag (reserved colour, written by the quota pauser) is not addressable: the API answers 404.

Use this to remove keywords from a tag without deleting the tag itself. The tag keeps its title, colour and date window; only the keyword assignments listed are cleared. Reversible with add_rank_radar_tag_search_terms, so no confirmation is required. Idempotent: ids that are not currently attached are left unchanged, so re-sending the same ids after a timeout is safe. Up to 1000 ids per call — split larger batches into multiple calls. To remove the tag itself, use delete_rank_radar_tag. The system "paused" tag (reserved colour, written by the quota pauser) is not addressable: the API answers 404.

Use this to permanently remove a tag from a Rank Radar. ⚠️ The tag itself is gone and the assignments linking it to each tagged keyword are removed with it; the keywords themselves keep tracking. The deletion cannot be undone from this tool, so set confirm: true only after the user approves. The system "paused" tag (reserved colour, written by the quota pauser) cannot be addressed from here — the API answers 404. To remove just the assignments and keep the tag, use remove_rank_radar_tag_search_terms instead.

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 an ASIN's inventory: stock levels, days of stock or when it will run out, low-inventory or aged-inventory risk, low-inventory-level (LILF) or long-term storage (LTSF) fees, or where their units sit across Amazon's fulfillment network. 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 the metrics the DataDive Inventory page shows — fulfillableStock, totalStock, reservedStock, inboundStock, researchingStock, unfulfillableStock, daysOfStock (with daysOfStockSource AMAZON or ESTIMATE), daysOfStock30, daysOfStock90, inLowInventoryState, estWeeklyLilf, estLtsfNextAssessment, ltsfLastMonthActual, agedUnits, oldestUnitAgeDays, with fees in currency — plus totalSellableUnits and a per-FC distribution array (fc, state, availableStock, availableStockPercentage). A metric is null, never 0, when Amazon has no data (e.g. merchant-fulfilled); metrics the user's plan does not include are null and listed in lockedFields (say they need a plan upgrade, do not report them as zero). lastUpdatedAt dates the stock and metrics; distributionLastUpdatedAt dates the distribution, which is usually up to 2 days behind. Either may be null when no successful refresh happened 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).