{"openapi":"3.1.0","paths":{"/v1/niches":{"get":{"description":"Retrieves a paginated list of Niches. Each Niche represents a market segment or product category being tracked. Supports narrowing by name (searchText) or by a competitor ASIN (searchAsin), and ordering by last dive date or name. Walk the pages with currentPage until hasNext is false.","operationId":"ExternalApiV1Controller_listNiches","parameters":[{"name":"spaces","required":false,"in":"query","description":"Only items in at least one of these Spaces (ids from GET /v1/spaces). Repeat the parameter or use `spaces[]=1&spaces[]=2`. At most 100. Combines with `labels` and the other filters with AND.","schema":{"maxItems":100,"example":[12,34],"type":"array","items":{"type":"number"}}},{"name":"labels","required":false,"in":"query","description":"Only items with at least one of these labels (ids from GET /v1/labels). Repeat the parameter or use `labels[]=1&labels[]=2`. At most 100. Combines with `spaces` and the other filters with AND.","schema":{"maxItems":100,"example":[12,34],"type":"array","items":{"type":"number"}}},{"name":"searchText","required":false,"in":"query","description":"Case-insensitive partial match on the Niche label or hero keyword","schema":{"example":"dog hat","type":"string"}},{"name":"searchAsin","required":false,"in":"query","description":"Only Niches whose competitor set contains this ASIN","schema":{"example":"B08N5WRWNW","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"Sort field. `lastDived` orders by latestResearchDate, `name` by nicheLabel.","schema":{"default":"lastDived","type":"string","enum":["lastDived","name"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction. Defaults to DESC for `lastDived` and ASC for `name`.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheList"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List all Niches","tags":["v1"]}},"/v1/niches/{nicheId}/keywords":{"get":{"description":"Retrieves the master keyword list for the specified niche. The master keyword list contains relevant search terms monitored for ranking and performance metrics.","operationId":"ExternalApiV1Controller_getMasterKeywordList","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GetMasterKeywordListResult"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (60 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get master keyword list for a niche","tags":["v1"]},"post":{"description":"Adds your own keywords to a Niche's Master Keyword List (MKL), the same way the web app does. Every submitted keyword a phrase exclusion does not block is reported in exactly one of these `originBreakdown` groups:\n\n- `alreadyInMkl` — already in the MKL; left untouched.\n- `takenFromOutliers` / `takenFromResidue` — moved into the MKL from the Outliers or Residue list. Free.\n- `addedManually` — new to the Niche. Ranked against the Niche's Competitors; relevancy can be 0.\n\nTwo groups report keywords that match one of the Niche's keyword exclusions:\n\n- `takenFromExcluded` — matched an exact exclusion. The exclusion is removed, so the keyword shows again; it is also listed in the group above it landed in.\n- `blockedByPhraseExclusion` — matched a phrase exclusion. The rule is left in place and the keyword is not added; it appears in no other group, and `matchedPhrase` names the rule to remove first.\n\n**Cost.** While the Niche is fresh (dived within the last 24 hours, or a Dive is already running) the add is free and the keywords are readable from GET /v1/niches/{nicheId}/keywords at once. Once it is stale, adding any new keyword re-dives the Niche with its current Competitors and consumes one Dive token per Competitor, like a `same_competitors` re-dive. The response then carries `refresh.diveId`; poll GET /v1/niches/dives/{diveId} until `success`, after which the keywords are in the MKL.\n\nSend `dryRun: true` first to see `tokensUsed` without saving or paying anything, then pass that figure as `maxTokensUsed` on the real call so it can never cost more than the dry run said. A dry run runs every check the real call does except the 422, which only the re-dive itself can discover. Undo an add with POST /v1/niches/{nicheId}/keywords/remove.\n\nRate limited to 2 requests per minute per Niche, dry runs included.","operationId":"ExternalApiV1Controller_addNicheKeywords","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddNicheKeywordsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/AddNicheKeywordsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body; or, for a stale Niche: it has fewer than 2 Competitors, its marketplace cannot be re-dived, the re-dive would cost more than `maxTokensUsed` (`error: \"MAX_TOKENS_EXCEEDED\"`), or there are not enough Dive tokens (`error: \"QUOTA_EXCEEDED\"`). Nothing is saved or charged.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MaxTokensExceededErrorDto"},{"$ref":"#/components/schemas/ExternalQuotaExceededErrorDto"}]}}}},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription, or, for a stale Niche, its number of Competitors exceeds your plan's limit"},"404":{"description":"Niche not found, or it has no completed research"},"422":{"description":"Stale Niche only: current product data could no longer be found for enough of the Niche's Competitors to re-dive. Nothing is saved and no Dive tokens are consumed. A dry run cannot predict this."},"429":{"description":"Rate limit exceeded (2 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Add keywords to a Niche's Master Keyword List","tags":["v1"]}},"/v1/niches/{nicheId}/outlier_keywords":{"get":{"description":"High search volume keywords that only a few of the niche competitors rank for, so they fall outside the master keyword list. Paginated: walk the pages with currentPage until hasNext is false.","operationId":"ExternalApiV1Controller_getOutlierKeywordPage","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the niche","schema":{"type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"The page of keywords to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of keywords per page. By default, it is 20. Max page size is 100","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/KeywordListPage"}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (60 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get the outlier keywords of a niche","tags":["v1"]}},"/v1/niches/{nicheId}/residue_keywords":{"get":{"description":"Keywords of the niche that are in neither the master keyword list nor the outlier list. Paginated: walk the pages with currentPage until hasNext is false.","operationId":"ExternalApiV1Controller_getResidueKeywordPage","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the niche","schema":{"type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"The page of keywords to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of keywords per page. By default, it is 20. Max page size is 100","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/KeywordListPage"}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (60 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get the residue keywords of a niche","tags":["v1"]}},"/v1/niches/{nicheId}/competitors":{"get":{"description":"Retrieves the list of Competitors within the specified Niche along with Niche statistics. For the Niche, returns keyword statistics, opportunity evaluation, and benchmark median values. For each Competitor, returns key business metrics including sales, revenue, number of variations, main image URL, and more.","operationId":"ExternalApiV1Controller_getCompetitorList","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GetCompetitorListResult"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (60 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Competitor list and Niche statistics","tags":["v1"]}},"/v1/niches/{nicheId}/ranking-juices":{"get":{"description":"Retrieves the Ranking Juices for each Competitor within the specified Niche. Ranking Juice is a DataDive proprietary metric that identifies the key factors driving search ranking success for each Competitor's listing. The API also returns the maximum Ranking Juice benchmark calculated using the keyword staffing method.","operationId":"ExternalApiV1Controller_calculateRankingJuices","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NicheRankingJuices"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (60 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Ranking Juices for a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/roots":{"get":{"description":"Retrieves the keyword lexical roots for the specified Niche. Roots are individual words or word combinations extracted from the Master Keyword List. For example, \"bluetooth headphones\" contains roots: \"bluetooth\", \"headphones\", and \"bluetooth headphones\". This analysis helps identify the most impactful keywords and their search volume distribution.","operationId":"ExternalApiV1Controller_getRootsForNiche","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalRootResponseDto"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get keyword roots for a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/ai-copywriter":{"post":{"description":"Starts an advanced-AI listing generation for the Niche and returns immediately with a `generationId`. Generation runs asynchronously — poll GET /v1/niches/:nicheId/ai-copywriter/:generationId until `status` is `complete` (result available) or `failed`.","operationId":"ExternalApiV1Controller_useAiCopywriterForNiche","parameters":[{"name":"nicheId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCopyWriterInputDto"}}}},"responses":{"401":{"description":"Api key is invalid"},"403":{"description":"AI Copywriter prompt quota exceeded (`error: \"QUOTA_EXCEEDED\"`), or no access to the niche","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalQuotaExceededErrorDto"}}}},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Use AI Copywriter for the niche","tags":["v1"]}},"/v1/niches/{nicheId}/ai-copywriter/{generationId}":{"get":{"description":"Retrieves the status of an advanced-AI listing generation started via POST /v1/niches/:nicheId/ai-copywriter. Returns different schemas based on state: generating (in progress), complete (with the generated listing), or failed (with an error). Poll this endpoint until the generation completes.","operationId":"ExternalApiV1Controller_getAiCopywriterStatus","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}},{"name":"generationId","required":true,"in":"path","description":"The generationId returned when the generation was started","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AiListingGenerationGeneratingResponseDto"},{"$ref":"#/components/schemas/AiListingGenerationCompleteResponseDto"},{"$ref":"#/components/schemas/AiListingGenerationFailedResponseDto"}]}}}},"400":{"description":"Invalid generationId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"AI listing generation not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get AI Copywriter generation status","tags":["v1"]}},"/v1/niches/{nicheId}":{"delete":{"description":"Deletes the specified Niche and all associated data including keywords, competitors, all dives and diveboxes. Note: A Niche cannot be deleted if it is used in any Rank Radar.","operationId":"ExternalApiV1Controller_deleteNiche","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Niche not found"},"409":{"description":"Niche cannot be deleted because it is used in a rank radar"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Deletes the Niche","tags":["v1"]}},"/v1/niches/rank-radars":{"get":{"description":"Retrieves a paginated list of Rank Radars. Rank Radars track keyword rankings over time for specific ASINs, monitoring organic and sponsored positions across search results. Returns summary metrics including top 10/50 keyword counts and search volumes. By default only active Rank Radars are returned; use the status filter for paused or archived ones.","operationId":"ExternalApiV1Controller_getRankRadarList","parameters":[{"name":"nicheId","required":false,"in":"query","description":"Filter Rank Radars by Niche identifier","schema":{"type":"string"}},{"name":"spaces","required":false,"in":"query","description":"Only items in at least one of these Spaces (ids from GET /v1/spaces). Repeat the parameter or use `spaces[]=1&spaces[]=2`. At most 100. Combines with `labels` and the other filters with AND.","schema":{"maxItems":100,"example":[12,34],"type":"array","items":{"type":"number"}}},{"name":"labels","required":false,"in":"query","description":"Only items with at least one of these labels (ids from GET /v1/labels). Repeat the parameter or use `labels[]=1&labels[]=2`. At most 100. Combines with `spaces` and the other filters with AND.","schema":{"maxItems":100,"example":[12,34],"type":"array","items":{"type":"number"}}},{"name":"status","required":false,"in":"query","description":"Filter by Rank Radar status. ACTIVE (the default) returns Rank Radars that are tracking; PAUSED returns those stopped via the archive endpoint; ARCHIVED returns those removed via DELETE; ALL returns active and paused together. Any other value is rejected with 400.","schema":{"enum":["ACTIVE","PAUSED","ARCHIVED","ALL"],"type":"string"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page. By default, it is 20. Max page size is 50","schema":{"example":20}},{"name":"currentPage","required":false,"in":"query","description":"The page of items to retrieve. By default, it is 1","schema":{"example":1}},{"name":"searchText","required":false,"in":"query","description":"Filter Rank Radars by ASIN or product title. An exact, case-insensitive ASIN match against any ASIN of the tracked variation family, so a variation finds the Rank Radar that tracks its family; otherwise a substring match on the product title.","schema":{}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRankRadarListResponseDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List all Rank Radars","tags":["v1"]},"post":{"description":"Creates a new Rank Radar to track keyword rankings for a specific ASIN within a Niche. The Rank Radar will monitor organic and sponsored rankings for the specified number of keywords. Rank Radar Search Term tokens are consumed based on the number of keywords tracked. Returns a rankRadarId for accessing the tracking data.\n\n**Warnings.** The response carries a `warnings` array of non-blocking notices about the creation, each with a machine-readable `code` and a `message` you can show to a user verbatim. It is empty when there is nothing to flag. Today the only code is `FAMILY_ALREADY_TRACKED`, returned when one of your existing Rank Radars already tracks an ASIN of the same variation family in the same marketplace — in this Niche or any other. That is allowed: two Rank Radars on one family let you track two different sets of search terms and keep separate statistics. It just costs Tracked Search Terms twice. Treat an unknown `code` as informational.\n\n**Previewing.** Send `dryRun: true` to run every check — validation, quota and the duplicate check — and get the same `warnings` back without creating anything: no Rank Radar, no Search Term tokens spent, no rows written. `rankRadarId` is `null` in that response. `dryRun` defaults to `false`, so omitting it behaves exactly as before.","operationId":"ExternalApiV1Controller_createRankRadar","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarSuccessResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarErrorResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a new Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}":{"get":{"description":"Retrieves historical keyword ranking data for the specified Rank Radar within a date range. Returns tracked keywords with their daily organic, sponsored, and impression rank positions. Use this to analyze ranking trends and performance over time. PPC and SQP keyword data are served by the dedicated `/v1/niches/rank-radars/{rankRadarId}/ppc` and `/v1/niches/rank-radars/{rankRadarId}/sqp` endpoints.","operationId":"ExternalApiV1Controller_getRankRadarKeywordList","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Start date for the ranking data range in yyyy-mm-dd format. The range can span at most 90 days","schema":{"example":"2024-03-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"End date for the ranking data range in yyyy-mm-dd format. The range can span at most 90 days","schema":{"example":"2024-03-26","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"The page of keywords to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of keywords per page. By default, it is 20. Max page size is 100","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KrtKeywordListResponseDto"}}}},"400":{"description":"Invalid rankRadarId, date format, or a date range longer than 90 days"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get keyword rankings for a Rank Radar","tags":["v1"]},"delete":{"description":"Deletes the specified Rank Radar and all associated keyword ranking data. Frees Daily Tracked Keywords quota.","operationId":"ExternalApiV1Controller_deleteRankRadar","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Invalid rankRadarId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Deletes the Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/sqp":{"get":{"description":"Retrieves aggregated Search Query Performance (SQP) data per tracked keyword for the specified Rank Radar within a date range — impressions, clicks, cart adds, and purchases (total and for this ASIN family), CTR/CVR, and Amazon's search query score/volume. Rate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_getRankRadarSqpData","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Start date for the SQP data range in yyyy-mm-dd format. The range can span at most 90 days","schema":{"example":"2024-03-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"End date for the SQP data range in yyyy-mm-dd format. The range can span at most 90 days","schema":{"example":"2024-03-26","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"The page of keywords to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of keywords per page. By default, it is 20. Max page size is 100","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarSqpKeywordListResponseDto"}}}},"400":{"description":"Invalid rankRadarId, date format, or a date range longer than 90 days"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Search Query Performance data for a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/ppc":{"get":{"description":"Retrieves per-keyword PPC data for the specified Rank Radar within a date range — sponsored rank, impression rank/share, match types hit, impressions, clicks, CTR, CPC, orders, PPC sales, spend, ACOS, and conversion rate. Pass `includeCampaigns=true` for a per-campaign/ad-group breakdown. Rate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_getRankRadarPpcData","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Start date for the PPC data range in yyyy-mm-dd format. The range can span at most 90 days","schema":{"example":"2024-03-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"End date for the PPC data range in yyyy-mm-dd format. The range can span at most 90 days","schema":{"example":"2024-03-26","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"The page of keywords to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of keywords per page. By default, it is 20. Max page size is 100","schema":{"example":20,"type":"number"}},{"name":"includeCampaigns","required":false,"in":"query","description":"Include a per-campaign/ad-group breakdown for each keyword","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarPpcKeywordListResponseDto"}}}},"400":{"description":"Invalid rankRadarId, date format, or a date range longer than 90 days"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get PPC data for a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/archive":{"post":{"description":"Archives (pauses) an active Rank Radar. Tracking stops for all of its keywords and the Daily Tracked Keywords quota is freed, but the Rank Radar and its historical data are retained. Rank Radars archived this way are listed with the status=PAUSED filter, not status=ARCHIVED (which covers those removed via DELETE), and are reactivated via the resume endpoint. This operation is idempotent: archiving an already-archived Rank Radar succeeds without changes.","operationId":"ExternalApiV1Controller_archiveRankRadar","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"responses":{"204":{"description":"Archived"},"400":{"description":"Invalid rankRadarId"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Archive a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/resume":{"post":{"description":"Resumes (reactivates) an archived Rank Radar. Keyword tracking is restarted for as many keywords as the available Daily Tracked Keywords quota allows, prioritizing the most relevant keywords. This operation is idempotent: resuming an already-active Rank Radar succeeds without changes.","operationId":"ExternalApiV1Controller_resumeRankRadar","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"responses":{"204":{"description":"Resumed"},"400":{"description":"Invalid rankRadarId, or Daily Tracked Keywords quota exceeded (`error: \"QUOTA_EXCEEDED\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalQuotaExceededErrorDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Resume a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/search-terms":{"post":{"description":"Adds manual search terms (keywords) to an existing Rank Radar for tracking. New keywords are added to the Niche and start being tracked, while any previously paused matching keywords are resumed. Daily Tracked Keywords quota is consumed for each newly tracked keyword. Returns the origin breakdown of the submitted terms and `keywordToRankRadarKeywordIdMap`, mapping each term to its Rank Radar keyword identifier.","operationId":"ExternalApiV1Controller_addRankRadarSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSearchTermsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalAddSearchTermsResponseDto"}}}},"400":{"description":"Invalid rankRadarId, invalid search terms, or Daily Tracked Keywords quota exceeded (`error: \"QUOTA_EXCEEDED\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalQuotaExceededErrorDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Add search terms to a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/search-terms/archive":{"post":{"description":"Archives (pauses) the specified search terms of a Rank Radar so they stop being tracked and their Daily Tracked Keywords quota is freed. Search terms are identified by their Rank Radar keyword identifiers (the `id` values returned by GET /v1/niches/rank-radars/:rankRadarId and the `keywordToRankRadarKeywordIdMap` values returned by the add search terms endpoint). This operation is idempotent: search terms that are already archived are left unchanged.","operationId":"ExternalApiV1Controller_archiveRankRadarSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarSearchTermIdsDto"}}}},"responses":{"204":{"description":"Archived"},"400":{"description":"Invalid rankRadarId or rankRadarKeywordIds"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Archive search terms of a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/search-terms/resume":{"post":{"description":"Resumes (unpauses) the specified archived search terms of a Rank Radar so they start being tracked again. Daily Tracked Keywords quota is consumed for each resumed search term. Search terms are identified by their Rank Radar keyword identifiers. This operation is idempotent: search terms that are already active are left unchanged.","operationId":"ExternalApiV1Controller_resumeRankRadarSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarSearchTermIdsDto"}}}},"responses":{"204":{"description":"Resumed"},"400":{"description":"Invalid rankRadarId, invalid rankRadarKeywordIds, or Daily Tracked Keywords quota exceeded (`error: \"QUOTA_EXCEEDED\"`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalQuotaExceededErrorDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Resume search terms of a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/tags":{"post":{"description":"Creates a user tag (\"highlight\") on a Rank Radar: a labelled, colour-coded span that can be attached to any of the Rank Radar's keywords. Titles must be unique on this Rank Radar (case-insensitive, trimmed); duplicates return 409 with the existing tag id. The reserved colour `#EB5757` is rejected with 400. `endAt` must be greater than or equal to `startAt`. Optional `rankRadarKeywordIds` attach the tag to those keywords on creation; they must all belong to this Rank Radar. The legacy `highlights` field on `GET /v1/niches/rank-radars/{rankRadarId}` keeps its existing shape and still surfaces these tags.","operationId":"ExternalApiV1Controller_createRankRadarTag","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarTagRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarTagResponseDto"}}}},"400":{"description":"Invalid rankRadarId, invalid body, reserved color `#EB5757`, `endAt` earlier than `startAt`, or one of `rankRadarKeywordIds` does not belong to this Rank Radar"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"409":{"description":"Another tag on this Rank Radar already uses this title (case-insensitive, trimmed). The response body carries the existing tag id so the caller can reconcile without a list call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarTagTitleConflictResponseDto"}}}},"429":{"description":"Rate limit exceeded (2 requests/min per API key per Rank Radar). A write on a different Rank Radar of the same organization is unaffected."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a tag for a Rank Radar","tags":["v1"]},"get":{"description":"Returns a paginated list of user tags (\"highlights\") on the specified Rank Radar, ordered by title (case-insensitive, ascending). Each item includes `keywordCount`, the number of Rank Radar keywords this tag is applied to. System tags are excluded. The legacy `highlights` field on `GET /v1/niches/rank-radars/{rankRadarId}` keeps its existing shape and still surfaces these tags.","operationId":"ExternalApiV1Controller_listRankRadarTags","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"The page of items to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page. By default, it is 20. Max page size is 100.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarTagListResponseDto"}}}},"400":{"description":"Invalid rankRadarId or pagination parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List tags for a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/tags/{tagId}":{"patch":{"description":"Updates the given tag on the Rank Radar. Any subset of `title`, `color`, `description`, `startAt`, `endAt` can be sent; omitted fields are left as-is. Keyword assignment is managed through a separate endpoint. Titles must remain unique on this Rank Radar (case-insensitive, trimmed); duplicates return 409 with the existing tag id. The reserved colour `#EB5757` is rejected with 400.","operationId":"ExternalApiV1Controller_updateRankRadarTag","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"tagId","required":true,"in":"path","description":"The unique identifier of the tag","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRankRadarTagRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarTagResponseDto"}}}},"400":{"description":"Invalid rankRadarId, invalid tagId, invalid body, reserved color `#EB5757`, or `endAt` earlier than `startAt`"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar or tag not found"},"409":{"description":"Another tag on this Rank Radar already uses this title (case-insensitive, trimmed). The response body carries the existing tag id so the caller can reconcile without a list call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarTagTitleConflictResponseDto"}}}},"429":{"description":"Rate limit exceeded (2 requests/min per API key per Rank Radar). A write on a different Rank Radar of the same organization is unaffected."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Update a tag on a Rank Radar","tags":["v1"]},"delete":{"description":"Permanently removes the tag and detaches it from every keyword it was applied to. The keywords themselves keep tracking.","operationId":"ExternalApiV1Controller_deleteRankRadarTag","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"tagId","required":true,"in":"path","description":"The unique identifier of the tag","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Invalid rankRadarId or tagId"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar or tag not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key per Rank Radar). A write on a different Rank Radar of the same organization is unaffected."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Delete a tag on a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/tags/{tagId}/search-terms":{"post":{"description":"Assigns the given tag to the specified Rank Radar Search Terms (keywords). All `rankRadarKeywordIds` must belong to this Rank Radar. Returns the tag, including the full list of keyword ids it is now assigned to (not just the ones passed in this request).","operationId":"ExternalApiV1Controller_attachTagsToSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"tagId","required":true,"in":"path","description":"The unique identifier of the tag","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignRankRadarTagToSearchTermsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignRankRadarTagToSearchTermsResponseDto"}}}},"400":{"description":"Invalid rankRadarId, invalid tagId, invalid body, or one or more rankRadarKeywordIds do not belong to this Rank Radar."},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar or tag not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key per Rank Radar). A write on a different Rank Radar of the same organization is unaffected."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Assign a tag to Rank Radar Search Terms","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/tags/{tagId}/search-terms/remove":{"post":{"description":"Removes the given tag from the specified Rank Radar Search Terms (keywords). All `rankRadarKeywordIds` must belong to this Rank Radar.","operationId":"ExternalApiV1Controller_removeAttachedTagsFromSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"tagId","required":true,"in":"path","description":"The unique identifier of the tag","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignRankRadarTagToSearchTermsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveAssignedRankRadarTagToSearchTermsResponseDto"}}}},"400":{"description":"Invalid rankRadarId, invalid tagId, invalid body, or one or more rankRadarKeywordIds do not belong to this Rank Radar."},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar or tag not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key per Rank Radar). A write on a different Rank Radar of the same organization is unaffected."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Remove assigned tag from Rank Radar Search Terms","tags":["v1"]}},"/v1/niches/dives":{"post":{"description":"Initiates a Niche Dive starting from a hero ASIN. The Niche Dive process automatically identifies and analyzes Competitors, extracts relevant keywords, and generates complete Niche research data. Dive tokens are consumed based on the number of Competitors specified. Returns a diveId to track the analysis progress.","operationId":"ExternalApiV1Controller_createDive","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveSuccessResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveErrorResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a new Niche Dive","tags":["v1"]}},"/v1/niches/dive_with_competitors":{"post":{"description":"Initiates a Niche Dive from a caller-provided list of Competitor ASINs — no automatic Competitor discovery is performed. Mirrors the \"ASIN tray → Create Niche\" flow in the extension. Dive tokens are consumed based on the number of ASINs supplied. Returns a diveId to track the analysis progress via GET /v1/niches/dives/{diveId}.","operationId":"ExternalApiV1Controller_createDiveWithCompetitors","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveWithCompetitorsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveWithCompetitorsResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveErrorResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"The number of ASINs exceeds your plan limit, or you are at your Niche limit"},"404":{"description":"Resource not found"},"422":{"description":"Current product data could not be found for enough of the given ASINs. No Dive tokens are consumed."},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a new Niche Dive from an explicit Competitor list","tags":["v1"]}},"/v1/niches/{nicheId}/redive":{"post":{"description":"Re-runs a Dive on an existing Niche to refresh its research data. Two modes:\n\n- `same_competitors` — re-dives the Niche's current Competitor set. Takes no other field.\n- `discover` — searches for a fresh Competitor set, keeping any `lockedAsins` and skipping any `excludedAsins` and any ASIN already excluded on the Niche. `excludedAsins` are saved to the Niche and apply to every later Dive. `numberOfCompetitors` is the total number of ASINs the refreshed Dive should contain, including the locked ones. `heroAsin` is the seed product discovery starts from; when omitted it defaults to the Niche Competitor with the highest sales, preferring one that belongs to one of your connected seller accounts.\n\nThe Dive runs asynchronously and consumes Dive tokens like any other Dive. Poll GET /v1/niches/dives/{diveId} with the returned `diveId` until the status is `success` or `error`. The refreshed data stays on the same `nicheId`; no new Niche is created.","operationId":"ExternalApiV1Controller_rediveNiche","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche to re-dive","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RediveNicheRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/RediveNicheResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body, a field that does not belong to the given mode, or not enough Dive tokens for the requested number of Competitors"},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription, or the requested number of Competitors exceeds your plan limit"},"404":{"description":"Niche not found, or it has no completed research to re-dive"},"422":{"description":"In `same_competitors` mode, current product data could no longer be found for enough of the Niche's Competitors to re-dive (for example they were delisted). No Dive tokens are consumed."},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Re-dive an existing Niche","tags":["v1"]}},"/v1/niches/{nicheId}/keywords/remove":{"post":{"description":"Undoes an add, by where each keyword came from:\n\n- `removedManual` — added by hand; deleted from the Niche.\n- `sentBackToOutliers` / `sentBackToResidue` — moved in from Outliers or Residue; listed there again, with their data kept.\n- `notRemovable` — found by the Dive itself, or not in the Niche; left unchanged.\n\nFree. Removing a keyword right after adding it leaves the Niche settings exactly as they were.\n\nRate limited to 2 requests per minute per Niche.","operationId":"ExternalApiV1Controller_removeNicheKeywords","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveNicheKeywordsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/RemoveNicheKeywordsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body"},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription"},"404":{"description":"Niche not found, or it has no completed research"},"429":{"description":"Rate limit exceeded (2 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Remove keywords from a Niche's Master Keyword List","tags":["v1"]}},"/v1/niches/{nicheId}/spaces":{"post":{"description":"Puts the Niche in the given Spaces, from GET /v1/spaces. A delta: Spaces you do not list are left as they are, and so are assignee tags. Ids already attached are counted in `added` / `alreadyPresent`, never errors.\n\nAll or nothing: if any id is not a Space of your organization the call fails with 404 and `unknownIds`, if the acting member cannot manage a Space it fails with 403 and `forbiddenSpaceIds`, and nothing changes. The acting member needs Manage access to the Niche; `x-api-key` calls act as the owner.\n\nRate limited to 2 requests per minute per Niche.","operationId":"ExternalApiV1Controller_addNicheSpaces","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheSpacesRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/AddNicheTagsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body"},"401":{"description":"Api key is invalid"},"403":{"description":"Spaces the acting member cannot manage (`forbiddenSpaceIds`), or the acting member cannot manage the Niche, or the Niche belongs to another subscription","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ForbiddenSpacesErrorDto"}]}}}},"404":{"description":"Niche not found, or ids that are not Spaces of your organization (`unknownIds`)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnknownTagIdsErrorDto"}]}}}},"429":{"description":"Rate limit exceeded (2 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Add Spaces to a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/spaces/remove":{"post":{"description":"Takes the Niche out of the given Spaces, from GET /v1/spaces. A delta: Spaces you do not list are left as they are, and so are assignee tags. Ids already detached are counted in `removed` / `notPresent`, never errors.\n\nAll or nothing: if any id is not a Space of your organization the call fails with 404 and `unknownIds`, if the acting member cannot manage a Space it fails with 403 and `forbiddenSpaceIds`, and nothing changes. The acting member needs Manage access to the Niche; `x-api-key` calls act as the owner.\n\nRate limited to 2 requests per minute per Niche.","operationId":"ExternalApiV1Controller_removeNicheSpaces","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheSpacesRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/RemoveNicheTagsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body"},"401":{"description":"Api key is invalid"},"403":{"description":"Spaces the acting member cannot manage (`forbiddenSpaceIds`), or the acting member cannot manage the Niche, or the Niche belongs to another subscription","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ForbiddenSpacesErrorDto"}]}}}},"404":{"description":"Niche not found, or ids that are not Spaces of your organization (`unknownIds`)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnknownTagIdsErrorDto"}]}}}},"429":{"description":"Rate limit exceeded (2 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Remove Spaces from a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/labels":{"post":{"description":"Puts the Niche in the given labels, from GET /v1/labels. A delta: labels you do not list are left as they are, and so are assignee tags. Ids already attached are counted in `added` / `alreadyPresent`, never errors.\n\nAll or nothing: if any id is not a label of your organization the call fails with 404 and `unknownIds`, and nothing changes. The acting member needs Manage access to the Niche; `x-api-key` calls act as the owner.\n\nRate limited to 2 requests per minute per Niche.","operationId":"ExternalApiV1Controller_addNicheLabels","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheLabelsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/AddNicheTagsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body"},"401":{"description":"Api key is invalid"},"403":{"description":"The acting member cannot manage the Niche, or the Niche belongs to another subscription"},"404":{"description":"Niche not found, or ids that are not labels of your organization (`unknownIds`)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnknownTagIdsErrorDto"}]}}}},"429":{"description":"Rate limit exceeded (2 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Add labels to a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/labels/remove":{"post":{"description":"Takes the Niche out of the given labels, from GET /v1/labels. A delta: labels you do not list are left as they are, and so are assignee tags. Ids already detached are counted in `removed` / `notPresent`, never errors.\n\nAll or nothing: if any id is not a label of your organization the call fails with 404 and `unknownIds`, and nothing changes. The acting member needs Manage access to the Niche; `x-api-key` calls act as the owner.\n\nRate limited to 2 requests per minute per Niche.","operationId":"ExternalApiV1Controller_removeNicheLabels","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheLabelsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/RemoveNicheTagsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body"},"401":{"description":"Api key is invalid"},"403":{"description":"The acting member cannot manage the Niche, or the Niche belongs to another subscription"},"404":{"description":"Niche not found, or ids that are not labels of your organization (`unknownIds`)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnknownTagIdsErrorDto"}]}}}},"429":{"description":"Rate limit exceeded (2 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Remove labels from a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/keyword-exclusions":{"get":{"description":"Lists the keywords excluded from a Niche's Master Keyword List, the same list the web app shows:\n\n- `exact` — each hides the one keyword that matches it exactly.\n- `phrase` — each hides every keyword containing the phrase, with how many keywords and how much search volume it hides.\n\nChange them with POST /v1/niches/{nicheId}/keyword-exclusions and POST /v1/niches/{nicheId}/keyword-exclusions/remove.","operationId":"ExternalApiV1Controller_getNicheKeywordExclusions","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/KeywordExclusionsDto"}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription"},"404":{"description":"Niche not found, or it has no completed research"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get a Niche's keyword exclusions","tags":["v1"]},"post":{"description":"Adds exact and phrase exclusions, the same way the web app does; the excluded keywords drop out of GET /v1/niches/{nicheId}/keywords at once. Only the exclusions change: every other Master Keyword List setting is kept.\n\nSend 1 to 100 entries in total across `exact` and `phrase`. Entries already excluded are reported under `unchanged`, so repeating a call is safe. A Niche can have at most 1000 exclusions, exact and phrase combined. Free.\n\nRate limited to 30 requests per minute per Niche.","operationId":"ExternalApiV1Controller_addNicheKeywordExclusions","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordExclusionsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/AddKeywordExclusionsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body, or the add would take the Niche past 1000 exclusions. Nothing is saved."},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription"},"404":{"description":"Niche not found, or it has no completed research"},"429":{"description":"Rate limit exceeded (30 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Exclude keywords from a Niche's Master Keyword List","tags":["v1"]}},"/v1/niches/{nicheId}/keyword-exclusions/remove":{"post":{"description":"Removes exact and phrase exclusions, so the keywords they hid show in the Master Keyword List again. Only the exclusions change: every other Master Keyword List setting is kept.\n\nSend 1 to 100 entries in total across `exact` and `phrase`. Entries that are not excluded are reported under `unchanged`, so repeating a call is safe. Free.\n\nRate limited to 30 requests per minute per Niche.","operationId":"ExternalApiV1Controller_removeNicheKeywordExclusions","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordExclusionsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/RemoveKeywordExclusionsResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body"},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription"},"404":{"description":"Niche not found, or it has no completed research"},"429":{"description":"Rate limit exceeded (30 requests/min per organization and Niche)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Remove keyword exclusions from a Niche's Master Keyword List","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/asins/{asin}/inventory":{"get":{"description":"Returns the inventory metrics of an ASIN for one of your connected seller accounts — stock by disposition, days of stock, low-inventory state, estimated low-inventory-level (LILF) and long-term storage (LTSF) fees, the last LTSF charged, and aged units — plus its sellable units at each Amazon fulfillment center. The values match the Product Catalog and Inventory pages.\n\n`distribution` includes every fulfillment center currently assigned to this ASIN, including those with `availableStock: 0` — useful for spotting regional stockouts. Only the sellable disposition is broken down by fulfillment center.\n\n**Dates.** `lastUpdatedAt` is the last daily refresh of live stock, which the metrics are based on. `distributionLastUpdatedAt` is the last refresh of `distribution`; Amazon publishes it with a delay, so it is usually up to 2 days behind. Either is `null` without a successful refresh in the last 30 days. `lastUpdatedAt` used to carry the distribution date.\n\n**Missing and locked data.** A metric is `null`, never `0`, when Amazon has no data for it (for example a merchant-fulfilled listing, or a connection without FBA inventory permission). Metrics your plan does not include are `null` and listed in `lockedFields`, with the reason in `lockedReason`. Fees are in `currency`, the marketplace currency.\n\nRate limited to approximately 60 requests per minute per API key.\n\nExample:\n```\ncurl -H \"x-api-key: $API_KEY\" \\\n  https://api.datadive.tools/v1/sellers/A1B2C3/marketplaces/com/asins/B0ABCDEFGH/inventory\n```","operationId":"ExternalApiV1Controller_getInventoryByFc","parameters":[{"name":"asin","required":true,"in":"path","description":"Amazon Standard Identification Number","schema":{"example":"B0ABCDEFGH"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryByFcResponseDto"}}}},"400":{"description":"Malformed sellerId, marketplace, or ASIN"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Caller cannot access inventory for this combination of seller, marketplace, and ASIN. Returned identically whether the seller is not owned by the caller or the ASIN is not in the catalog (prevents seller/ASIN enumeration)."},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get inventory metrics and per-fulfillment-center distribution for an ASIN","tags":["v1"]}},"/v1/alerts/indexing-issues":{"get":{"description":"Returns a paginated list of indexing-issue alerts across your connected Amazon seller accounts. An indexing-issue alert fires when one of your ASINs is no longer indexed for its tracked keywords. Results are scoped to your organization. Optionally filter by `sellerId`, `marketplace`, lifecycle `status`, and `updatedSince` (for incremental polling). Defaults to active alerts from the last 30 days. Rate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_listIndexingIssueAlerts","parameters":[{"name":"sellerId","required":false,"in":"query","description":"Filter to a single Amazon seller account you have connected to DataDive","schema":{"example":"A1B2C3D4E5","type":"string"}},{"name":"marketplace","required":false,"in":"query","description":"Filter to a single Amazon marketplace code (e.g. com, co.uk, de, ca)","schema":{"example":"com","type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]}},{"name":"status","required":false,"in":"query","description":"Lifecycle filter. `active` (default) returns unresolved alerts, `resolved` returns resolved alerts, `all` returns both. Dismissed alerts are never returned.","schema":{"default":"active","type":"string","enum":["active","resolved","all"]}},{"name":"updatedSince","required":false,"in":"query","description":"Return only alerts surfaced at or after this ISO-8601 timestamp (filters on `lastAlertedAt`, i.e. when the alert was created). Use this to incrementally sync since your last poll. Defaults to the last 30 days when omitted.","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexingIssueAlertListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List indexing-issue alerts","tags":["v1"]}},"/v1/alerts/blind-spend":{"get":{"description":"Returns a paginated list of blind-spend alerts across your connected Amazon seller accounts. A blind-spend alert flags ad spend on customer search terms that produced little or no sales; each alert embeds its unresolved wasted-spend search terms with spend/clicks/CVR. Results are scoped to your organization. Optionally filter by `sellerId`, `marketplace`, lifecycle `status`, and `updatedSince` (for incremental polling). Defaults to active alerts from the last 30 days. Rate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_listBlindSpendAlerts","parameters":[{"name":"sellerId","required":false,"in":"query","description":"Filter to a single Amazon seller account you have connected to DataDive","schema":{"example":"A1B2C3D4E5","type":"string"}},{"name":"marketplace","required":false,"in":"query","description":"Filter to a single Amazon marketplace code (e.g. com, co.uk, de, ca)","schema":{"example":"com","type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]}},{"name":"status","required":false,"in":"query","description":"Lifecycle filter. `active` (default) returns unresolved alerts, `resolved` returns resolved alerts, `all` returns both. Dismissed alerts are never returned.","schema":{"default":"active","type":"string","enum":["active","resolved","all"]}},{"name":"updatedSince","required":false,"in":"query","description":"Return only alerts surfaced at or after this ISO-8601 timestamp (filters on `lastAlertedAt`, i.e. when the alert was created). Use this to incrementally sync since your last poll. Defaults to the last 30 days when omitted.","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlindSpendAlertListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List wasted-spend (blind spend) alerts","tags":["v1"]}},"/v1/seller_profiles":{"get":{"description":"Returns a paginated list of Amazon seller profiles connected to your organization. Use the sellerId and marketplace from these results to query seller-specific endpoints such as catalog and inventory.","operationId":"ExternalApiV1Controller_listSellerProfiles","parameters":[{"name":"currentPage","required":false,"in":"query","description":"The page of items to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page. By default, it is 20. Max page size is 50","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerProfileListDto"}}}},"400":{"description":"Invalid pagination parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List seller profiles","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/catalog":{"get":{"description":"Returns a paginated list of ASINs from the product catalog for the specified seller account and marketplace. Supports filtering by search text (title/brand), brand name, and product status. Defaults to Active products only; pass status=all to include all statuses.","operationId":"ExternalApiV1Controller_listCatalogAsins[0]","parameters":[{"name":"search","required":false,"in":"query","description":"Partial match on product title or brand","schema":{"example":"wireless earbuds","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Partial match on brand name","schema":{"example":"Anker","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by product status. Defaults to \"Active\". Use \"all\" to include every status except \"Deleted\" (listings the seller removed from Amazon). Only listings reported by Amazon in the last 30 days are returned.","schema":{"default":"Active","example":"Active","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogAsinListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List catalog ASINs for a seller","tags":["v1"]}},"/v1/seller_profiles/{sellerId}/marketplaces/{marketplace}/catalog":{"get":{"description":"Returns a paginated list of ASINs from the product catalog for the specified seller account and marketplace. Supports filtering by search text (title/brand), brand name, and product status. Defaults to Active products only; pass status=all to include all statuses.","operationId":"ExternalApiV1Controller_listCatalogAsins[1]","parameters":[{"name":"search","required":false,"in":"query","description":"Partial match on product title or brand","schema":{"example":"wireless earbuds","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Partial match on brand name","schema":{"example":"Anker","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by product status. Defaults to \"Active\". Use \"all\" to include every status except \"Deleted\" (listings the seller removed from Amazon). Only listings reported by Amazon in the last 30 days are returned.","schema":{"default":"Active","example":"Active","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogAsinListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List catalog ASINs for a seller","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/listing-changes":{"get":{"description":"Returns a paginated list of listing changes (price, content, image) detected for the specified seller account and marketplace. Optionally filter by ASIN, brand, date range, and change type. Set `includeCorrelations=true` to enrich each change with before/after sales and ranking metrics.","operationId":"ExternalApiV1Controller_listListingChanges[0]","parameters":[{"name":"types","required":false,"in":"query","description":"Comma-separated listing change types to filter by (Price, Content, Image). Defaults to all.","schema":{"type":"array","items":{"type":"string"}}},{"name":"asin","required":false,"in":"query","description":"Filter by exact ASIN or parent ASIN","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Filter by brand name (partial match)","schema":{"example":"Anker","type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by title or brand (partial match)","schema":{"example":"wireless earbuds","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date filter (ISO 8601)","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date filter (ISO 8601)","schema":{"example":"2024-07-01T00:00:00Z","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort field","schema":{"default":"date","type":"string","enum":["date","type"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"includeCorrelations","required":false,"in":"query","description":"Include before/after metric correlations for each change","schema":{"default":false,"type":"boolean"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingChangesExternalListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List listing changes for a seller","tags":["v1"]}},"/v1/seller_profiles/{sellerId}/marketplaces/{marketplace}/listing-changes":{"get":{"description":"Returns a paginated list of listing changes (price, content, image) detected for the specified seller account and marketplace. Optionally filter by ASIN, brand, date range, and change type. Set `includeCorrelations=true` to enrich each change with before/after sales and ranking metrics.","operationId":"ExternalApiV1Controller_listListingChanges[1]","parameters":[{"name":"types","required":false,"in":"query","description":"Comma-separated listing change types to filter by (Price, Content, Image). Defaults to all.","schema":{"type":"array","items":{"type":"string"}}},{"name":"asin","required":false,"in":"query","description":"Filter by exact ASIN or parent ASIN","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Filter by brand name (partial match)","schema":{"example":"Anker","type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by title or brand (partial match)","schema":{"example":"wireless earbuds","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date filter (ISO 8601)","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date filter (ISO 8601)","schema":{"example":"2024-07-01T00:00:00Z","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort field","schema":{"default":"date","type":"string","enum":["date","type"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"includeCorrelations","required":false,"in":"query","description":"Include before/after metric correlations for each change","schema":{"default":false,"type":"boolean"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingChangesExternalListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List listing changes for a seller","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/ppc/campaigns":{"get":{"description":"Returns a paginated list of Sponsored Products campaigns for the specified seller account and marketplace, each with totals for the reporting window (impressions, clicks, spend, sales, units, orders, CTR, CPC, ACOS, ROAS) and, by default, a per-placement breakdown with that placement bid adjustment. Optionally narrow to the campaigns advertising one ASIN (`asin`) or one variation family (`parentAsin`).\n\nThe reporting window defaults to the last 30 days and cannot exceed 90 days.\n\nRate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_listPpcCampaigns[0]","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start of the reporting window (ISO 8601). Defaults to 30 days before `endDate`.","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End of the reporting window (ISO 8601). Defaults to now.","schema":{"example":"2024-07-01T00:00:00Z","type":"string"}},{"name":"asin","required":false,"in":"query","description":"Only campaigns advertising this ASIN. Cannot be combined with parentAsin.","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"parentAsin","required":false,"in":"query","description":"Only campaigns advertising any ASIN of this variation family. Cannot be combined with asin.","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"search","required":false,"in":"query","description":"Partial match on campaign name or advertised ASIN. Minimum 3 characters.","schema":{"example":"auto","type":"string"}},{"name":"includePlacements","required":false,"in":"query","description":"Include the per-placement breakdown (top of search, rest of search, product page, off Amazon) with each placement bid adjustment. Set to false for a smaller, faster response.","schema":{"default":true,"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","description":"Sort field. Placement fields are only accepted when includePlacements is true.","schema":{"default":"name","type":"string","enum":["name","state","bidStrategy","budget","impressions","clicks","ctr","cpc","spend","unitsSold","sales","acos","roas","cvr","tosImpressionShare","targetingType","orders","tosImpressions","tosClicks","tosSpend","tosSales","tosUnitsSold","rosImpressions","rosClicks","rosSpend","rosSales","rosUnitsSold","ppImpressions","ppClicks","ppSpend","ppSales","ppUnitsSold","offImpressions","offClicks","offSpend","offSales","offUnitsSold","tosBidAdjustment","rosBidAdjustment","ppBidAdjustment","tosCtr","tosCpc","tosAcos","tosRoas","rosCtr","rosCpc","rosAcos","rosRoas","ppCtr","ppCpc","ppAcos","ppRoas","offCtr","offCpc","offAcos","offRoas","tosCvr","rosCvr","ppCvr","offCvr","tosOrders","rosOrders","ppOrders","offOrders"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"state","required":false,"in":"query","description":"Filter by campaign state. Omit to return both ENABLED and PAUSED.","schema":{"type":"string","enum":["ENABLED","PAUSED"]}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PpcCampaignsExternalListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List PPC campaigns with placement performance","tags":["v1"]}},"/v1/seller_profiles/{sellerId}/marketplaces/{marketplace}/ppc/campaigns":{"get":{"description":"Returns a paginated list of Sponsored Products campaigns for the specified seller account and marketplace, each with totals for the reporting window (impressions, clicks, spend, sales, units, orders, CTR, CPC, ACOS, ROAS) and, by default, a per-placement breakdown with that placement bid adjustment. Optionally narrow to the campaigns advertising one ASIN (`asin`) or one variation family (`parentAsin`).\n\nThe reporting window defaults to the last 30 days and cannot exceed 90 days.\n\nRate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_listPpcCampaigns[1]","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start of the reporting window (ISO 8601). Defaults to 30 days before `endDate`.","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End of the reporting window (ISO 8601). Defaults to now.","schema":{"example":"2024-07-01T00:00:00Z","type":"string"}},{"name":"asin","required":false,"in":"query","description":"Only campaigns advertising this ASIN. Cannot be combined with parentAsin.","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"parentAsin","required":false,"in":"query","description":"Only campaigns advertising any ASIN of this variation family. Cannot be combined with asin.","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"search","required":false,"in":"query","description":"Partial match on campaign name or advertised ASIN. Minimum 3 characters.","schema":{"example":"auto","type":"string"}},{"name":"includePlacements","required":false,"in":"query","description":"Include the per-placement breakdown (top of search, rest of search, product page, off Amazon) with each placement bid adjustment. Set to false for a smaller, faster response.","schema":{"default":true,"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","description":"Sort field. Placement fields are only accepted when includePlacements is true.","schema":{"default":"name","type":"string","enum":["name","state","bidStrategy","budget","impressions","clicks","ctr","cpc","spend","unitsSold","sales","acos","roas","cvr","tosImpressionShare","targetingType","orders","tosImpressions","tosClicks","tosSpend","tosSales","tosUnitsSold","rosImpressions","rosClicks","rosSpend","rosSales","rosUnitsSold","ppImpressions","ppClicks","ppSpend","ppSales","ppUnitsSold","offImpressions","offClicks","offSpend","offSales","offUnitsSold","tosBidAdjustment","rosBidAdjustment","ppBidAdjustment","tosCtr","tosCpc","tosAcos","tosRoas","rosCtr","rosCpc","rosAcos","rosRoas","ppCtr","ppCpc","ppAcos","ppRoas","offCtr","offCpc","offAcos","offRoas","tosCvr","rosCvr","ppCvr","offCvr","tosOrders","rosOrders","ppOrders","offOrders"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"state","required":false,"in":"query","description":"Filter by campaign state. Omit to return both ENABLED and PAUSED.","schema":{"type":"string","enum":["ENABLED","PAUSED"]}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PpcCampaignsExternalListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List PPC campaigns with placement performance","tags":["v1"]}},"/v1/fast-keywords":{"post":{"description":"Finds the keywords a single ASIN ranks for, grouped into roots, with its top Competitors. Costs 1 Dive token. Poll GET /v1/fast-keywords/{fastKeywordsId} with the returned `fastKeywordsId` until `status` is `success` or `failed`. A fresh result for the same product is reused and returns `success` right away.\n\n**Previewing.** Send `dryRun: true` to get `tokenCost` and `hasEnoughTokens` without running anything.","operationId":"ExternalApiV1Controller_runFastKeywords","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunFastKeywordsRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"oneOf":[{"$ref":"#/components/schemas/FastKeywordsRunResponseDto"},{"$ref":"#/components/schemas/FastKeywordsRunPreviewResponseDto"}]}}}}}},"400":{"description":"Invalid ASIN or marketplace, or not enough Dive tokens"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"},"503":{"description":"Our product data provider is rate-limited. No token was spent; try again in a few minutes."}},"security":[{"apiKey":[]}],"summary":"Run Fast Keywords","tags":["v1"]},"get":{"description":"Lists the Fast Keywords results requested by anyone in your organization, most recently requested first. Narrow by ASIN, title or brand (search) and by marketplace. Walk the pages with currentPage until hasNext is false.","operationId":"ExternalApiV1Controller_listFastKeywords","parameters":[{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 100)","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive partial match on ASIN, title or brand","schema":{"example":"dog hat","type":"string"}},{"name":"marketplace","required":false,"in":"query","schema":{"example":"com","type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FastKeywordsListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List Fast Keywords results","tags":["v1"]}},"/v1/fast-keywords/{fastKeywordsId}/refresh":{"post":{"description":"Runs Fast Keywords again for a result you requested before, updating it in place under the same `fastKeywordsId`. Costs 1 Dive token. A result can be refreshed once every 24 hours, and not while a run is in progress.\n\n**Previewing.** Send `dryRun: true` to run the same checks and get `tokenCost` and `hasEnoughTokens` without running anything.","operationId":"ExternalApiV1Controller_refreshFastKeywords","parameters":[{"name":"fastKeywordsId","required":true,"in":"path","description":"The Fast Keywords result to refresh","schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshFastKeywordsRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"oneOf":[{"$ref":"#/components/schemas/FastKeywordsRunResponseDto"},{"$ref":"#/components/schemas/FastKeywordsRunPreviewResponseDto"}]}}}}}},"400":{"description":"Invalid fastKeywordsId, or not enough Dive tokens"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"No Fast Keywords result with this id was requested by you"},"409":{"description":"A run is in progress (`IN_PROGRESS`), or the result was refreshed less than 24 hours ago (`COOLDOWN`, with `nextEligibleAt`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FastKeywordsRefreshConflictResponseDto"}}}},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"},"503":{"description":"Our product data provider is rate-limited. No token was spent; try again in a few minutes."}},"security":[{"apiKey":[]}],"summary":"Refresh Fast Keywords","tags":["v1"]}},"/v1/spaces":{"get":{"description":"Returns the Spaces of your organization as a tree. Use their ids wherever a route or filter takes a Space id. A call with an API key sees every Space; an MCP connection sees only the Spaces its member can use or manage.","operationId":"ExternalApiV1Controller_getSpaceTree","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalTagTreeDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List Spaces","tags":["v1"]}},"/v1/labels":{"get":{"description":"Returns the labels of your organization as a tree. Use their ids wherever a route or filter takes a label id. Labels have no access rights, so every caller sees all of them.","operationId":"ExternalApiV1Controller_getLabelTree","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalTagTreeDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List labels","tags":["v1"]}},"/v1/quota":{"get":{"description":"Returns current quota usage and capacity for all billable features, along with the next quota refresh date.","operationId":"ExternalApiV1Controller_getQuotaUsage","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalQuotaResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get quota usage","tags":["v1"]}},"/v1/usage":{"get":{"description":"Returns a paginated list of billable feature usage logs for your organization. Each entry represents a token consumption event (e.g. a dive, rank radar creation, AI copywriter prompt). Optionally filter by feature type, user name/email, and date range.","operationId":"ExternalApiV1Controller_getUsageLogs","parameters":[{"name":"type","required":false,"in":"query","description":"Filter by billable feature type","schema":{"type":"string","enum":["DIVED_ASINS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","RANK_RADAR_KEYWORDS","INDEXING_DIAGNOSIS","REVIEW_REQUEST_ASINS"]}},{"name":"search","required":false,"in":"query","description":"Search by user name or email (case-insensitive partial match)","schema":{"example":"john","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter usage logs created on or after this date (ISO 8601)","schema":{"example":"2024-01-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter usage logs created on or before this date (ISO 8601)","schema":{"example":"2024-12-31T23:59:59Z","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 50, max 200)","schema":{"minimum":1,"maximum":200,"example":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalUsageLogListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List billable feature usage logs","tags":["v1"]}},"/v1/fast-keywords/{fastKeywordsId}":{"get":{"description":"Poll this after running Fast Keywords until `status` is `success` or `failed`. On success it returns the product, its variations, the keyword roots and the top 10 Competitors; read the keywords themselves with GET /v1/fast-keywords/{fastKeywordsId}/keywords. On failure, `failureReason` and `failureMessage` say why. A successful run that found very few keywords sets `insufficientKeywordData`.","operationId":"ExternalApiV1Controller_getFastKeywords","parameters":[{"name":"fastKeywordsId","required":true,"in":"path","description":"The Fast Keywords result","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/FastKeywordsResultDto"}}}]}}}},"400":{"description":"Invalid fastKeywordsId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Nobody in your organization requested this Fast Keywords result"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get a Fast Keywords result","tags":["v1"]}},"/v1/fast-keywords/{fastKeywordsId}/keywords":{"get":{"description":"Pages through the keywords a Fast Keywords result found, highest search volume first, with their organic and sponsored rank for the ASIN. A result can hold over 10,000 keywords.","operationId":"ExternalApiV1Controller_getFastKeywordsKeywords","parameters":[{"name":"fastKeywordsId","required":true,"in":"path","description":"The Fast Keywords result","schema":{"type":"number"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 100)","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/FastKeywordsKeywordListDto"}}}]}}}},"400":{"description":"Invalid fastKeywordsId or paging parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Nobody in your organization requested this Fast Keywords result"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get the keywords of a Fast Keywords result","tags":["v1"]}},"/v1/niches/dives/{diveId}":{"get":{"description":"Retrieves the current status of a Niche Dive analysis. Returns different response schemas based on the Dive state: in_progress (with estimated completion time), success (with nicheId and token usage), or error (with error details). Poll this endpoint to track the progress of a Dive until completion.","operationId":"ExternalApiV1Controller_getDiveStatus","parameters":[{"name":"diveId","required":true,"in":"path","description":"The unique identifier of the Dive","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NicheDiveStatusSuccessResponseDto"},{"$ref":"#/components/schemas/NicheDiveStatusInProgressResponseDto"},{"$ref":"#/components/schemas/NicheDiveStatusErrorResponseDto"}]}}}},"400":{"description":"Invalid diveId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Niche Dive status","tags":["v1"]}}},"info":{"title":"Data Dive Developer APIs","description":"\n  An API key is required to call the APIs in this page. The key must be set in the header named <b>x-api-key</b>.\n  <p>Example: call a Data-Dive api with curl</p>\n\n  ```bash\n  curl -X 'GET' \\\n  'https://api.datadive.tools/v1/mkl/z515cGOFg3' \\\n  -H 'accept: application/json' \\\n  -H 'x-api-key: apikey1234abcdefghij0123456789'\n  ```\n  \n  ## Webhook Events\n\n  Webhook events are delivered as HTTP POST requests to your configured webhook URL. To set up, edit, or archive webhooks, navigate to **Data Dive > Your account > [Integrations](https://2.datadive.tools/integrations)**. From there you can:\n\n  * Provide your endpoint destination URL.\n  * Subscribe to specific event topics.\n  ","version":"1.0.0","contact":{}},"tags":[],"servers":[{"url":"https://api.datadive.tools"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key on DataDive","scheme":"apiKey"}},"schemas":{"NicheItem":{"type":"object","properties":{"nicheId":{"type":"string","example":"z515cGOFg3","description":"The unique identifier of the Niche"},"heroKeyword":{"type":"string","example":"dog hat","description":"The primary keyword that defines the Niche"},"nicheLabel":{"type":"string","example":"Dog-hat opportunity","description":"A human-readable label for the Niche"},"marketplace":{"type":"string","example":"com","description":"The Amazon marketplace domain (e.g., com, uk, de)"},"latestResearchDate":{"type":"object","description":"The date when the Niche data was last updated"},"spaces":{"example":[12,34],"description":"Ids of the Spaces the Niche is in (see GET /v1/spaces). For an MCP member, only Spaces they can see.","type":"array","items":{"type":"number"}},"labels":{"example":[7],"description":"Ids of the labels on the Niche (see GET /v1/labels)","type":"array","items":{"type":"number"}}},"required":["nicheId","heroKeyword","nicheLabel","marketplace","latestResearchDate","spaces","labels"]},"NicheList":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/NicheItem"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ResponseDto":{"type":"object","properties":{"message":{"type":"string","example":["request successfully processed"]},"data":{"type":"object"}}},"BidInfo":{"type":"object","properties":{"min":{"type":"number","description":"Min bid. For USD, the value is in cent. For example: 101 means $1.01"},"max":{"type":"number","description":"Max bid. For USD, the value is in cent. For example: 886 means $8.86"},"median":{"type":"number","description":"Average bid. For USD, the value is in cent. For example: 445 means $4.45"}},"required":["min","max","median"]},"MklKeywordOrigin":{"type":"string","enum":["mkl","manual","outlier","residue"],"description":"Where the keyword comes from: `mkl` - found by the dive and placed in the Master Keywords List; `manual` - added by hand; `outlier` - moved in from the Outliers list; `residue` - moved in from the Residue list. A keyword in several of those lists takes the first of manual, outlier, residue. Relevancy is the share (0 to 1) of the niche's competitor ASINs ranking in the top 45: `outlier` and `residue` keywords keep the relevancy from the last dive, `manual` keywords get it from a fresh rank lookup and can be 0, and `mkl` keywords are always above 0."},"MasterKeywordListItem":{"type":"object","properties":{"keyword":{"type":"string","description":"The search term or keyword phrase"},"searchVolume":{"type":"number","description":"Monthly search volume for this keyword on Amazon"},"relevancy":{"type":"object","description":"Relevancy score indicating how well the keyword matches the Niche. Can be \"Outlier\" or a numeric score."},"asinRanks":{"type":"object","example":{"B09DCJJ9R3":2,"B09JZSHN73":4,"B09512SA73":null},"description":"Competitor ASINs organic ranks for this keyword. Null indicates the product is not ranked in the first pages."},"suggestedBid":{"nullable":true,"description":"Exact-match suggested bid (in cents). Null when not yet fetched for the latest dive.","type":"object","allOf":[{"$ref":"#/components/schemas/BidInfo"}]},"origin":{"example":"mkl","description":"Where the keyword comes from: `mkl` - found by the dive and placed in the Master Keywords List; `manual` - added by hand; `outlier` - moved in from the Outliers list; `residue` - moved in from the Residue list. A keyword in several of those lists takes the first of manual, outlier, residue. Relevancy is the share (0 to 1) of the niche's competitor ASINs ranking in the top 45: `outlier` and `residue` keywords keep the relevancy from the last dive, `manual` keywords get it from a fresh rank lookup and can be 0, and `mkl` keywords are always above 0.","allOf":[{"$ref":"#/components/schemas/MklKeywordOrigin"}]}},"required":["keyword","searchVolume","relevancy","asinRanks","suggestedBid","origin"]},"GetMasterKeywordListResult":{"type":"object","properties":{"keywords":{"description":"List of search terms in Master Keywords List with their search volume, relevancy, Competitors ranks, and exact-match suggested bid (in cents; null when not yet fetched for the latest dive)","type":"array","items":{"$ref":"#/components/schemas/MasterKeywordListItem"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["keywords","latestResearchDate"]},"MasterKeyword":{"type":"object","properties":{"keyword":{"type":"string","description":"The search term or keyword phrase"},"searchVolume":{"type":"number","description":"Monthly search volume for this keyword on Amazon"},"relevancy":{"type":"object","description":"Relevancy score indicating how well the keyword matches the Niche. Can be \"Outlier\" or a numeric score."},"asinRanks":{"type":"object","example":{"B09DCJJ9R3":2,"B09JZSHN73":4,"B09512SA73":null},"description":"Competitor ASINs organic ranks for this keyword. Null indicates the product is not ranked in the first pages."},"suggestedBid":{"nullable":true,"description":"Exact-match suggested bid (in cents). Null when not yet fetched for the latest dive.","type":"object","allOf":[{"$ref":"#/components/schemas/BidInfo"}]}},"required":["keyword","searchVolume","relevancy","asinRanks","suggestedBid"]},"KeywordListPage":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/MasterKeyword"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data","latestResearchDate"]},"MklStatisticsData":{"type":"object","properties":{"numKeywords":{"type":"number"},"numVisibleKeywords":{"type":"number"},"numMaxVisibleKeywords":{"type":"number"},"totalSvOfKeywords":{"type":"number"},"totalSvOfVisibleKeywords":{"type":"number"},"totalSvOfVisibleOutlierKeywords":{"type":"number"},"totalSvOfResidueKeywords":{"type":"number"}},"required":["numKeywords","numVisibleKeywords","numMaxVisibleKeywords","totalSvOfKeywords","totalSvOfVisibleKeywords","totalSvOfVisibleOutlierKeywords","totalSvOfResidueKeywords"]},"NumericOpportunityValue":{"type":"object","properties":{"value":{"type":"number","example":49.5},"opportunity":{"type":"string","enum":["none","veryGoodOpportunity","goodOpportunity","badOpportunity","veryBadOpportunity"],"example":"goodOpportunity"}},"required":["value","opportunity"]},"OpportunityEvaluation":{"type":"object","properties":{"competitionSvStrength":{"$ref":"#/components/schemas/NumericOpportunityValue"},"competitionKwStrength":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numRelevantKeywords":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numRelevantSearchVolume":{"type":"number"},"medianDaysListed":{"$ref":"#/components/schemas/NumericOpportunityValue"},"medianReviewCount":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numLaunchKeywords":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numLaunchSearchVolume":{"type":"number"}},"required":["competitionSvStrength","competitionKwStrength","numRelevantKeywords","numRelevantSearchVolume","medianDaysListed","medianReviewCount","numLaunchKeywords","numLaunchSearchVolume"]},"NumericCompetitorStrengthValue":{"type":"object","properties":{"value":{"type":"number","example":10.12},"competitorStrength":{"type":"string","enum":["none","veryStrongCompetitor","strongCompetitor","weakCompetitor","veryWeakCompetitor"],"example":"weakCompetitor"}},"required":["value","competitorStrength"]},"MklBenchmark":{"type":"object","properties":{"rating":{"type":"object","example":3.6},"reviewCount":{"type":"object","example":39},"listingCreationDate":{"$ref":"#/components/schemas/NumericCompetitorStrengthValue"},"price":{"type":"object","example":11.34},"sales":{"type":"object","example":376.5,"deprecated":true},"salesLowerRange":{"type":"object","example":11.34},"salesHigherRange":{"type":"object","example":376.5},"revenue":{"type":"object","example":4384.225,"deprecated":true},"revenueLowerRange":{"type":"object","example":4384.225},"revenueHigherRange":{"type":"object","example":4384.225},"outlierKeywords":{"type":"object","example":100},"outlierSV":{"type":"object","example":100},"kwRankedOnP1":{"type":"object","example":100},"kwRankedOnP1Percent":{"type":"object","example":100},"svRankedOnP1":{"type":"object","example":100},"svRankedOnP1Percent":{"type":"object","example":100},"kwRankedOnP1Evaluation":{"type":"object","example":"veryGood"},"svRankedOnP1Evaluation":{"type":"object","example":"veryGood"},"advertisedKws":{"type":"object","example":100},"advertisedKwsPercent":{"type":"object","example":100},"tosKwsAds":{"type":"object","example":100},"tosKwsAdsPercent":{"type":"object","example":100},"tosKwsAdsEvaluation":{"type":"object","example":"veryGood"},"tosSvAds":{"type":"object","example":100},"tosSvAdsPercent":{"type":"object","example":100},"tosSvAdsEvaluation":{"type":"object","example":"veryGood"},"numberOfVariations":{"type":"object","example":24}},"required":["rating","reviewCount","listingCreationDate","price","sales","salesLowerRange","salesHigherRange","revenue","revenueLowerRange","revenueHigherRange","outlierKeywords","outlierSV","kwRankedOnP1","kwRankedOnP1Percent","svRankedOnP1","svRankedOnP1Percent","kwRankedOnP1Evaluation","svRankedOnP1Evaluation","advertisedKws","advertisedKwsPercent","tosKwsAds","tosKwsAdsPercent","tosKwsAdsEvaluation","tosSvAds","tosSvAdsPercent","tosSvAdsEvaluation","numberOfVariations"]},"CompetitorsStrengthRanksValues":{"type":"object","properties":{"sellers":{"type":"number","example":2},"percentage":{"type":"number","example":0.6,"minimum":0,"maximum":1}},"required":["sellers","percentage"]},"CompetitorsStrengthRanks":{"type":"object","properties":{"veryStrongCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"strongCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"weakCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"veryWeakCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"none":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"}},"required":["veryStrongCompetitor","strongCompetitor","weakCompetitor","veryWeakCompetitor","none"]},"CompetitorsStrength":{"type":"object","properties":{"searchVolume":{"$ref":"#/components/schemas/CompetitorsStrengthRanks"},"keywords":{"$ref":"#/components/schemas/CompetitorsStrengthRanks"}},"required":["searchVolume","keywords"]},"AsinCatalogInfo":{"type":"object","properties":{"asin":{"type":"string"},"sellerId":{"type":"string"},"marketplace":{"type":"string"}},"required":["asin","sellerId","marketplace"]},"CompetitorListingRankingJuice":{"type":"object","properties":{"value":{"type":"number","description":"Total Ranking Juice for the entire listing","example":300456}},"required":["value"]},"CompetitorListItem":{"type":"object","properties":{"numberOfActiveSellers":{"type":"object","description":"Number","example":1},"asin":{"type":"string","description":"ASIN","example":"B07VHN2VCR"},"brand":{"type":"object","description":"Brand","example":"COLORWORK"},"title":{"type":"string","description":"Title","example":"COLORWORK DIY Paint by Numbers"},"fulfillment":{"type":"string","description":"Fulfillment","example":"FBA","enum":["AMZ","FBA","FBM","MFN"]},"price":{"type":"object","description":"Price","example":25},"sales":{"type":"object","description":"Sales","example":429},"revenue":{"type":"object","description":"Revenue","example":5143.71},"bsr":{"type":"object","description":"BSR","example":25250},"rating":{"type":"object","description":"Rating","example":5},"reviewCount":{"type":"object","description":"Review Count","example":3},"imageUrl":{"type":"object","description":"Semicolon (;) separated Urls of the images of the product","example":"https://images-na.ssl-images-amazon.com/images/I/41TfNcpwXXL.jpg","format":"uri"},"sellerCountry":{"type":"string","default":"N/A"},"listingCreationDate":{"type":"number","example":1644339094484,"description":"When the listing was created, in milliseconds since epoch. Absent when Amazon publishes no date."},"listingCreationDateEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"veryGood","description":"How mature this listing is for the Niche, scored against its average-days-listed thresholds. Older listings score higher. Empty string when the listing is 0 days old."},"outlierKws":{"type":"integer","example":43},"outlierSV":{"type":"integer","example":66082},"numberOfVariations":{"type":"integer","example":24},"kwRankedOnP1":{"type":"number"},"kwRankedOnP1Percent":{"type":"number"},"kwRankedOnP1Evaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"svRankedOnP1":{"type":"number"},"svRankedOnP1Percent":{"type":"number"},"svRankedOnP1Evaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"advertisedKws":{"type":"number"},"advertisedKwsPercent":{"type":"number"},"advertisedKwsEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"tosKwsAds":{"type":"number"},"tosKwsAdsPercent":{"type":"number"},"tosKwsAdsEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"tosSvAds":{"type":"number"},"tosSvAdsPercent":{"type":"number"},"tosSvAdsEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"asinCatalog":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AsinCatalogInfo"}]},"category":{"type":"object","example":"Arts, Crafts & Sewing","nullable":true},"categoryTree":{"type":"object","example":"Pet Supplies > Dogs > Apparel & Accessories","nullable":true},"listingRankingJuice":{"description":"Total Ranking Juice of this Competitor listing. Use GET /v1/niches/{nicheId}/ranking-juices for the breakdown by title, bullets and description.","allOf":[{"$ref":"#/components/schemas/CompetitorListingRankingJuice"}]}},"required":["numberOfActiveSellers","asin","brand","title","fulfillment","price","sellerCountry","outlierKws","outlierSV","numberOfVariations","kwRankedOnP1","kwRankedOnP1Percent","svRankedOnP1","svRankedOnP1Percent","advertisedKws","advertisedKwsPercent","tosKwsAds","tosKwsAdsPercent","tosSvAds","tosSvAdsPercent","asinCatalog","category","categoryTree","listingRankingJuice"]},"GetCompetitorListResult":{"type":"object","properties":{"marketplace":{"type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"],"description":"The Amazon marketplace for this Niche"},"statistics":{"description":"Statistical analysis of the Master Keyword List including keyword count, search volume distribution, and ranking metrics","allOf":[{"$ref":"#/components/schemas/MklStatisticsData"}]},"opportunityEvaluation":{"description":"Evaluation scores across multiple criteria (competition strength, keyword relevance, market maturity) indicating the Niche opportunity level","allOf":[{"$ref":"#/components/schemas/OpportunityEvaluation"}]},"benchmark":{"description":"Benchmark median values for key metrics (ratings, reviews, price, sales, revenue, keyword rankings) across all Competitors","allOf":[{"$ref":"#/components/schemas/MklBenchmark"}]},"competitorsStrength":{"description":"Overall strength assessment of Competitors in the Niche","allOf":[{"$ref":"#/components/schemas/CompetitorsStrength"}]},"competitors":{"description":"List of Competitors with their business metrics including ASIN, title, BSR, sales, revenue, ratings, reviews, price, category, images, and ranking data","type":"array","items":{"$ref":"#/components/schemas/CompetitorListItem"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["marketplace","statistics","opportunityEvaluation","benchmark","competitorsStrength","competitors","latestResearchDate"]},"RankingJuiceProperty":{"type":"object","properties":{"rankingJuice":{"type":"number","description":"Ranking Juice value for this specific listing property","example":1144}},"required":["rankingJuice"]},"ListingRankingJuice":{"type":"object","properties":{"rankingJuice":{"type":"number","description":"Total Ranking Juice value for the entire listing","example":300456},"title":{"description":"Ranking Juice contribution from the product title","allOf":[{"$ref":"#/components/schemas/RankingJuiceProperty"}]},"bullets":{"description":"Ranking Juice contribution from the bullet points","allOf":[{"$ref":"#/components/schemas/RankingJuiceProperty"}]},"description":{"description":"Ranking Juice contribution from the product description","allOf":[{"$ref":"#/components/schemas/RankingJuiceProperty"}]}},"required":["rankingJuice","title","bullets","description"]},"CompetitorRankingJuice":{"type":"object","properties":{"asin":{"type":"string","description":"ASIN of the Competitor product","example":"B00JXQQNC6"},"listing":{"description":"Ranking Juice for this Competitor's listing","allOf":[{"$ref":"#/components/schemas/ListingRankingJuice"}]}},"required":["asin","listing"]},"NicheRankingJuices":{"type":"object","properties":{"currentListing":{"description":"Ranking Juice for the current listing","allOf":[{"$ref":"#/components/schemas/ListingRankingJuice"}]},"optimizedListing":{"description":"Ranking Juice for the optimized listing using keyword staffing method to achieve maximum potential","allOf":[{"$ref":"#/components/schemas/ListingRankingJuice"}]},"competitors":{"description":"List of Competitors with their Listing Ranking Juices","type":"array","items":{"$ref":"#/components/schemas/CompetitorRankingJuice"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["currentListing","optimizedListing","competitors","latestResearchDate"]},"CombineKeywordResponseDto":{"type":"object","properties":{"keyword":{"type":"string","description":"Original keyword"},"searchVolume":{"type":"number","description":"Search Volume of Original Keyword"},"normalizedKeyword":{"type":"string","description":"Normalized Keyword, removed stop word from Original Keyword"},"normalizedSearchVolume":{"type":"number","description":"Search Volume of Normalized Keyword"},"relevancy":{"type":"number"},"cpr8dayGiveAways":{"type":"object","description":"is an estimation of the total units you would need to give away over an 8-day period to rank on page 1"},"competingProducts":{"type":"object"},"numberOfexacts":{"type":"number","description":"Give us the number of EXACTs in competitors title"},"rankingJuice":{"type":"number"}},"required":["keyword","searchVolume","normalizedKeyword","normalizedSearchVolume","relevancy","cpr8dayGiveAways","competingProducts","numberOfexacts","rankingJuice"]},"ConsolidatedResponseDto":{"type":"object","properties":{"normalizedKeyword":{"type":"string","description":"Normalized Keyword, removed stop words from Original Keyword"},"consolidatedSearchVolume":{"type":"number","description":"Addition of Original Keyword or Keywords Search Volume"}},"required":["normalizedKeyword","consolidatedSearchVolume"]},"RootsTableItem":{"type":"object","properties":{"root":{"type":"string","example":"dog","description":"Roots are the keyword or the group of keywords that are part of the original keyword"},"frequency":{"type":"number","example":51,"description":"Count of Root in the whole list of original keywords"},"broadSearchVolume":{"type":"number","example":77188,"description":"Sum of all Original Keyword Search Volume where the Root keyword is present"},"broadSearchVolumeRatio":{"type":"number","format":"float","example":0.700931693939449,"minimum":0,"maximum":1,"description":"Divide the broadSearchVolume by maxBroadSearchVolume to get this ratio"}},"required":["root","frequency","broadSearchVolume","broadSearchVolumeRatio"]},"ExternalRootResponseDto":{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/CombineKeywordResponseDto"}},"consolidatedKeywords":{"type":"array","items":{"$ref":"#/components/schemas/ConsolidatedResponseDto"}},"roots":{"type":"array","items":{"$ref":"#/components/schemas/RootsTableItem"}},"normalizedRoots":{"type":"array","items":{"$ref":"#/components/schemas/RootsTableItem"}},"latestResearchDate":{"format":"date-time","type":"string","description":"last successful research date for the niche"}},"required":["keywords","consolidatedKeywords","roots","normalizedRoots","latestResearchDate"]},"AiCopyWriterInputDto":{"type":"object","properties":{"prompt":{"type":"string","example":"cosmo|ranking-juice|nlp|cosmo-rufus","enum":["cosmo","ranking-juice","nlp","cosmo-rufus"]},"listingToInclude":{"type":"object","example":"{ \"title\": \"Title Example\", \"description\": \"Description Example\". \"bullets\":\"bullet1\nbullet2\n\"}"}},"required":["prompt","listingToInclude"]},"ExternalQuotaExceededErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"error":{"type":"string","example":"QUOTA_EXCEEDED","description":"Stable discriminant for this error"},"message":{"type":"string","example":"Quota exceeded"},"success":{"type":"boolean","example":false},"subscriptionUrl":{"type":"string","example":"https://2.datadive.tools/subscription/overview","description":"Subscription page where the quota can be raised"},"feature":{"type":"string","enum":["DIVED_ASINS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","RANK_RADAR_KEYWORDS","INDEXING_DIAGNOSIS","REVIEW_REQUEST_ASINS"],"example":"RANK_RADAR_KEYWORDS","description":"Billable feature that ran out"},"used":{"type":"object","example":5000,"nullable":true,"description":"Current usage count"},"capacity":{"type":"object","example":5000,"nullable":true,"description":"Quota capacity"},"nextRefreshDate":{"type":"object","example":"2024-04-15T00:00:00.000Z","nullable":true,"description":"ISO 8601 timestamp of next quota reset"}},"required":["statusCode","error","message","success","subscriptionUrl"]},"AiListingGenerationGeneratingResponseDto":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier of the generation attempt","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"status":{"type":"string","enum":["generating","complete","failed"],"description":"Current status: generating (in progress), complete (result available), or failed (generation errored)","example":"generating"}},"required":["generationId","status"]},"AiListingGenerationResultDto":{"type":"object","properties":{"rankingJuice":{"type":"object","description":"Ranking Juice metrics for the generated listing (value + per-field contribution).","additionalProperties":true},"title":{"type":"string","description":"Generated product title","example":"Stainless Steel Water Bottle 32oz"},"itemHighlights":{"type":"string","description":"Item highlights, if generated","example":""},"bullets":{"description":"Generated bullet points","type":"array","items":{"type":"string"}},"description":{"type":"string","description":"Generated product description"},"methodology_breakdown":{"type":"object","description":"Methodology breakdown of the generation, when produced by the model","additionalProperties":true}},"required":["rankingJuice","title","itemHighlights","bullets","description"]},"AiListingGenerationCompleteResponseDto":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier of the generation attempt","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"status":{"type":"string","enum":["generating","complete","failed"],"description":"Current status: generating (in progress), complete (result available), or failed (generation errored)","example":"generating"},"result":{"description":"The generated listing","allOf":[{"$ref":"#/components/schemas/AiListingGenerationResultDto"}]}},"required":["generationId","status","result"]},"AiListingGenerationFailedResponseDto":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier of the generation attempt","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"status":{"type":"string","enum":["generating","complete","failed"],"description":"Current status: generating (in progress), complete (result available), or failed (generation errored)","example":"generating"},"error":{"type":"string","description":"Human-readable error describing why the generation failed"}},"required":["generationId","status","error"]},"ExternalRankRadarStatus":{"type":"string","enum":["ACTIVE","PAUSED","ARCHIVED","ALL"],"description":"Uses the same vocabulary as the status query parameter, except the filter-only ALL"},"KRTAsinResponseDto":{"type":"object","properties":{"id":{"type":"string"},"krtId":{"type":"string"},"asin":{"type":"string"}},"required":["id","krtId","asin"]},"ExternalRankRadarResponseDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"description":"Uses the same vocabulary as the status query parameter, except the filter-only ALL","example":"ACTIVE","allOf":[{"$ref":"#/components/schemas/ExternalRankRadarStatus"}]},"asin":{"$ref":"#/components/schemas/KRTAsinResponseDto"},"marketplace":{"type":"string"},"keywordCount":{"type":"number"},"title":{"type":"string"},"imageUrl":{"type":"string"},"top10KW":{"type":"object"},"top10SV":{"type":"object"},"top50KW":{"type":"object"},"top50SV":{"type":"object"}},"required":["id","status","asin","marketplace","keywordCount","title","imageUrl","top10KW","top10SV","top50KW","top50SV"]},"ExternalRankRadarListResponseDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/ExternalRankRadarResponseDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ExternalKrtAsinRankDto":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO format"},"organicRank":{"type":"object","example":1},"sponsoredRank":{"type":"object","example":1,"description":"Sponsored (PPC) search-results rank","nullable":true},"impressionRank":{"type":"object","example":1}},"required":["date","organicRank","sponsoredRank","impressionRank"]},"KrtHighlightDto":{"type":"object","properties":{"id":{"type":"string","description":"Highlight ID"},"krtId":{"type":"string","description":"KRT Id related to highlight"},"krtKeywordId":{"type":"string","description":"krtKeywordId related to highlight"},"title":{"type":"string","description":"Title of Highlight"},"description":{"type":"object","description":"Description of Highlight","example":"something great"},"color":{"type":"object","description":"Color of Highlight","example":"green"},"type":{"type":"string","description":"Type of Highlight"},"startAt":{"type":"object","description":"Start Date of Highlight","example":"2024-07-12"},"endAt":{"type":"object","description":"End Date of Highlight","example":"2024-07-12"},"searchVolume":{"type":"number","description":"Search Volume of related keywords"},"svShare":{"type":"number","description":"Search Volume share of related keywords"},"keywords":{"description":"Related keywords","type":"array","items":{"type":"string"}}},"required":["id","krtId","krtKeywordId","title","description","color","type","startAt","endAt","searchVolume","svShare","keywords"]},"KrtKeywordResponseDto":{"type":"object","properties":{"id":{"type":"string"},"keyword":{"type":"string","example":"keyword"},"searchVolume":{"type":"object","example":123},"ranks":{"type":"array","items":{"$ref":"#/components/schemas/ExternalKrtAsinRankDto"}},"highlights":{"type":"array","items":{"$ref":"#/components/schemas/KrtHighlightDto"}},"relevancy":{"type":"object","description":"Phrase relevancy score for this keyword within its Niche"}},"required":["id","keyword","searchVolume","ranks","highlights"]},"KrtKeywordListResponseDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/KrtKeywordResponseDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"RankRadarSqpKeywordDto":{"type":"object","properties":{"id":{"type":"string"},"keyword":{"type":"string","example":"keyword"},"numberOfDaysWithData":{"type":"object","description":"Days in the requested range with SQP data available","nullable":true},"cartAddsTotalCount":{"type":"object","description":"Total cart-add count across all sellers for this keyword","nullable":true},"cartAddsAsinCount":{"type":"object","description":"This ASIN family's cart-add count for this keyword","nullable":true},"cartAddsAsinShare":{"type":"object","description":"This ASIN family's share of cart adds for this keyword","nullable":true},"cartAddsCartAddRate":{"type":"object","description":"cartAddsAsinCount / searchQueryVolume","nullable":true},"clicksTotalCount":{"type":"object","description":"Total click count across all sellers for this keyword","nullable":true},"clicksAsinCount":{"type":"object","description":"This ASIN family's click count for this keyword","nullable":true},"clicksAsinShare":{"type":"object","description":"This ASIN family's share of clicks for this keyword","nullable":true},"clicksClickRate":{"type":"object","description":"clicksAsinCount / searchQueryVolume","nullable":true},"impressionsTotalCount":{"type":"object","description":"Total impression count across all sellers for this keyword","nullable":true},"impressionsAsinCount":{"type":"object","description":"This ASIN family's impression count for this keyword","nullable":true},"impressionsAsinShare":{"type":"object","description":"This ASIN family's share of impressions for this keyword","nullable":true},"purchasesTotalCount":{"type":"object","description":"Total purchase count across all sellers for this keyword","nullable":true},"purchasesAsinCount":{"type":"object","description":"This ASIN family's purchase count for this keyword","nullable":true},"purchasesAsinShare":{"type":"object","description":"This ASIN family's share of purchases for this keyword","nullable":true},"purchasesPurchaseRate":{"type":"object","description":"purchasesAsinCount / searchQueryVolume","nullable":true},"searchQueryScore":{"type":"object","description":"Amazon's Search Query Performance relevance score for this keyword","nullable":true},"searchQueryVolume":{"type":"object","description":"Total search volume for this keyword across the range","nullable":true},"ctrTotal":{"type":"object","description":"Click-through rate across all sellers","nullable":true},"ctrAsin":{"type":"object","description":"This ASIN family's click-through rate","nullable":true},"cvrTotal":{"type":"object","description":"Conversion rate across all sellers","nullable":true},"cvrAsin":{"type":"object","description":"This ASIN family's conversion rate","nullable":true}},"required":["id","keyword","numberOfDaysWithData","cartAddsTotalCount","cartAddsAsinCount","cartAddsAsinShare","cartAddsCartAddRate","clicksTotalCount","clicksAsinCount","clicksAsinShare","clicksClickRate","impressionsTotalCount","impressionsAsinCount","impressionsAsinShare","purchasesTotalCount","purchasesAsinCount","purchasesAsinShare","purchasesPurchaseRate","searchQueryScore","searchQueryVolume","ctrTotal","ctrAsin","cvrTotal","cvrAsin"]},"RankRadarSqpKeywordListResponseDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/RankRadarSqpKeywordDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"RankRadarAdGroupResponseDto":{"type":"object","properties":{"campaignId":{"type":"number"},"campaignName":{"type":"string"},"adGroupName":{"type":"string"},"matchType":{"type":"object","nullable":true},"costPerClicks":{"type":"object","nullable":true},"totalImpressions":{"type":"object","nullable":true},"totalOrders":{"type":"object","nullable":true},"totalClicks":{"type":"object","nullable":true},"ppcSpend":{"type":"object","nullable":true},"ppcSales":{"type":"object","nullable":true},"clickThroughRate":{"type":"object","nullable":true},"conversionRate":{"type":"object","nullable":true},"acos":{"type":"object","nullable":true},"targeting":{"type":"object","nullable":true}},"required":["campaignId","campaignName","adGroupName","matchType","costPerClicks","totalImpressions","totalOrders","totalClicks","ppcSpend","ppcSales","clickThroughRate","conversionRate","acos","targeting"]},"RankRadarPpcKeywordDto":{"type":"object","properties":{"id":{"type":"string"},"keyword":{"type":"string","example":"keyword"},"sponsoredRank":{"type":"object","description":"Median sponsored (PPC) search-results rank over the requested range","nullable":true},"impressionRank":{"type":"object","description":"Aggregated impression rank","nullable":true},"impressionRankShare":{"type":"object","description":"Aggregated impression rank share","nullable":true},"exactMatches":{"type":"object","description":"Count of exact-match campaigns hit","nullable":true},"phraseMatches":{"type":"object","description":"Count of phrase-match campaigns hit","nullable":true},"broadMatches":{"type":"object","description":"Count of broad-match campaigns hit","nullable":true},"autoMatches":{"type":"object","description":"Count of auto-match campaigns hit","nullable":true},"organicSales":{"type":"object","description":"Organic sales attributed to this keyword","nullable":true},"ppcSales":{"type":"object","description":"PPC sales attributed to this keyword"},"ppcSpend":{"type":"object","description":"PPC spend for this keyword"},"costPerClicks":{"type":"object","description":"Cost per click for this keyword"},"clickThroughRate":{"type":"object","description":"Sponsored click-through rate"},"conversionRate":{"type":"object","description":"Sponsored conversion rate"},"totalClicks":{"type":"number","description":"Total sponsored clicks"},"totalImpressions":{"type":"number","description":"Total sponsored impressions"},"totalOrders":{"type":"number","description":"Total sponsored orders"},"acos":{"type":"number","description":"Advertising cost of sales"},"campaigns":{"description":"Per-campaign/ad-group breakdown, only present when includeCampaigns=true was requested","type":"array","items":{"$ref":"#/components/schemas/RankRadarAdGroupResponseDto"}}},"required":["id","keyword","sponsoredRank","impressionRank","impressionRankShare","exactMatches","phraseMatches","broadMatches","autoMatches","organicSales","ppcSales","ppcSpend","costPerClicks","clickThroughRate","conversionRate","totalClicks","totalImpressions","totalOrders","acos"]},"RankRadarPpcKeywordListResponseDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/RankRadarPpcKeywordDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"AddSearchTermsRequestDto":{"type":"object","properties":{}},"ExternalAddSearchTermsResponseDto":{"type":"object","properties":{"originBreakdown":{"type":"object","readOnly":true,"example":{"manual":["puppy","outfits"],"suggestions":["dog raincoat"],"outliers":["dog swig","dog swim"],"residues":["mini cowboy","dog umbrella"],"paused":["sunglasses"]}},"keywordToRankRadarKeywordIdMap":{"type":"object","readOnly":true,"example":{"sunglasses":"rank-radar-keyword-id"}}},"required":["originBreakdown","keywordToRankRadarKeywordIdMap"]},"RankRadarSearchTermIdsDto":{"type":"object","properties":{"rankRadarKeywordIds":{"description":"The Rank Radar keyword identifiers to update. These are the `id` values returned by GET /v1/niches/rank-radars/:rankRadarId and the `keywordToRankRadarKeywordIdMap` values returned by the add search terms endpoint.","type":"array","items":{"type":"string"}}},"required":["rankRadarKeywordIds"]},"CreateRankRadarTagRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"Display title. Trimmed on write; must be unique per Rank Radar, case-insensitive.","example":"Promo week","minLength":1,"maxLength":100},"color":{"type":"string","description":"Hex colour in `#RRGGBB` form. Defaults to the UI grey `#C9CFD7` when omitted. The reserved colour `#EB5757` is rejected with 400.","example":"#C9CFD7"},"description":{"type":"string","description":"Free-form description","example":"Prime Day run-up"},"startAt":{"type":"string","description":"Start date (ISO 8601). Required if `endAt` is set; `endAt >= startAt`.","example":"2026-07-01"},"endAt":{"type":"string","description":"End date (ISO 8601). Must be greater than or equal to `startAt`.","example":"2026-07-14"},"rankRadarKeywordIds":{"description":"Rank Radar keyword ids (`id` values from GET /v1/niches/rank-radars/:rankRadarId) to tag on creation. Must all belong to this Rank Radar.","maxItems":1000,"type":"array","items":{"type":"string"}}},"required":["title"]},"RankRadarTagResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"title":{"type":"string","example":"Promo week"},"color":{"type":"string","example":"#C9CFD7","nullable":true},"description":{"type":"string","example":"Prime Day run-up","nullable":true},"startAt":{"type":"string","example":"2026-07-01T00:00:00.000Z","nullable":true},"endAt":{"type":"string","example":"2026-07-14T00:00:00.000Z","nullable":true},"keywordCount":{"type":"number","example":3,"description":"Number of Rank Radar keywords this tag is applied to."},"createdAt":{"type":"string","example":"2026-07-01T00:00:00.000Z","nullable":true}},"required":["id","title","color","description","startAt","endAt","keywordCount","createdAt"]},"RankRadarTagTitleConflictResponseDto":{"type":"object","properties":{"error":{"type":"string","example":"TAG_TITLE_EXISTS","enum":["TAG_TITLE_EXISTS"]},"existingTagId":{"type":"string","description":"The id of the tag that already uses this title on this Rank Radar.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"}},"required":["error","existingTagId"]},"RankRadarTagListResponseDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/RankRadarTagResponseDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"UpdateRankRadarTagRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"New title. Trimmed on write; must be unique per Rank Radar, case-insensitive.","example":"Promo week v2","minLength":1,"maxLength":100},"color":{"type":"string","description":"Hex colour in `#RRGGBB` form. The reserved colour `#EB5757` is rejected with 400.","example":"#C9CFD7"},"description":{"type":"string","description":"Free-form description. Pass `\"\"` to clear.","example":"Prime Day run-up"},"startAt":{"type":"string","description":"Start date (ISO 8601). `endAt >= startAt`.","example":"2026-07-01"},"endAt":{"type":"string","description":"End date (ISO 8601). `endAt >= startAt`.","example":"2026-07-14"}}},"AssignRankRadarTagToSearchTermsRequestDto":{"type":"object","properties":{"rankRadarKeywordIds":{"description":"Rank Radar keyword ids (`id` values from GET /v1/niches/rank-radars/:rankRadarId) to tag on creation. Must all belong to this Rank Radar.","maxItems":1000,"type":"array","items":{"type":"string"}}}},"AssignRankRadarTagToSearchTermsResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"title":{"type":"string","example":"Promo week"},"color":{"type":"string","example":"#C9CFD7","nullable":true},"description":{"type":"string","example":"Prime Day run-up","nullable":true},"startAt":{"type":"string","example":"2026-07-01T00:00:00.000Z","nullable":true},"endAt":{"type":"string","example":"2026-07-14T00:00:00.000Z","nullable":true},"keywordCount":{"type":"number","example":3,"description":"Number of Rank Radar keywords this tag is applied to."},"createdAt":{"type":"string","example":"2026-07-01T00:00:00.000Z","nullable":true},"keywordIds":{"example":["asds-asdnks-naksldnlas-sasdasd"],"nullable":false,"type":"array","items":{"type":"string"}}},"required":["id","title","color","description","startAt","endAt","keywordCount","createdAt","keywordIds"]},"RemoveAssignedRankRadarTagToSearchTermsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true,"nullable":false}},"required":["success"]},"CreateNicheDiveRequestDto":{"type":"object","properties":{"marketplace":{"type":"string","description":"The Amazon marketplace where the seed product is listed","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"asin":{"type":"string","description":"The seed ASIN to start the Niche Dive analysis from. The system will identify related Competitors and build the Niche around this product.","example":"B08N5WRWNW"},"numberOfCompetitors":{"type":"number","description":"Number of Competitors to include in the Niche analysis. More Competitors provide deeper insights but consume more Dive tokens. Minimum is 2.","example":5,"minimum":2},"fastKeywordsRequestId":{"type":"number","description":"Links the Niche Dive to a Fast Keywords run. Pass the `requestId` returned by POST /v1/fast-keywords or POST /v1/fast-keywords/{fastKeywordsId}/refresh, not the `fastKeywordsId`. An id that is not yours is ignored.","example":1256}},"required":["marketplace","asin","numberOfCompetitors","fastKeywordsRequestId"]},"CreateNicheDiveSuccessResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier for the Dive. Use this ID to check the Dive status and retrieve results when complete.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the Niche Dive analysis in ISO 8601 format","example":"2024-04-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"CreateNicheDiveErrorResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message describing why the Dive creation failed","example":"Invalid marketplace"},"errorId":{"type":"string","description":"Unique identifier for this error instance, useful for troubleshooting and support","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"}},"required":["error","errorId"]},"CreateNicheDiveWithCompetitorsRequestDto":{"type":"object","properties":{"marketplace":{"type":"string","description":"The Amazon marketplace where the given ASINs are listed","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"asins":{"description":"The explicit list of Competitor ASINs to build the Niche from. No automatic Competitor discovery is performed — the Niche Dive runs on exactly these ASINs. Dive tokens are consumed for each one.","example":["B08N5WRWNW","B09617YV4C"],"minItems":2,"maxItems":200,"uniqueItems":true,"type":"array","items":{"type":"string"}}},"required":["marketplace","asins"]},"CreateNicheDiveWithCompetitorsResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier for the Dive. Use this ID to check the Dive status and retrieve results when complete.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the Niche Dive analysis in ISO 8601 format","example":"2024-04-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"RediveNicheResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier for the re-dive. Poll `GET /v1/niches/dives/{diveId}` with it to track progress.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the re-dive in ISO 8601 format","example":"2026-08-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"RediveNicheRequestDto":{"type":"object","properties":{"mode":{"type":"string","description":"How to pick the Competitors for the refreshed Dive. `same_competitors` re-dives the Niche's current Competitor set and takes no other field. `discover` searches for a fresh Competitor set.","enum":["same_competitors","discover"],"example":"discover"},"numberOfCompetitors":{"type":"integer","description":"Total number of ASINs the refreshed Dive should contain, including `lockedAsins`. Required in `discover` mode and rejected in `same_competitors` mode. Dive tokens are consumed for each ASIN.","example":12,"minimum":2},"heroAsin":{"type":"string","description":"Seed product the Competitor discovery starts from. Defaults to the Niche Competitor with the highest sales, preferring one that belongs to one of your connected seller accounts. `discover` mode only.","example":"B08N5WRWNW"},"lockedAsins":{"description":"ASINs that must be kept in the refreshed Competitor set regardless of what discovery finds. `discover` mode only.","example":["B08N5WRWNW","B09617YV4C"],"uniqueItems":true,"maxItems":200,"type":"array","items":{"type":"string"}},"excludedAsins":{"description":"ASINs that discovery must never select. `discover` mode only. They are saved as exclusions on the Niche, so every later Dive of this Niche skips them as well. ASINs already excluded on the Niche are always skipped, whether or not they are repeated here; list one in `lockedAsins` to dive it anyway. An ASIN cannot be in both `lockedAsins` and `excludedAsins`.","example":["B07XHRSRZ2"],"uniqueItems":true,"maxItems":200,"type":"array","items":{"type":"string"}}},"required":["mode"]},"MaxTokensExceededErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"error":{"type":"object","example":"MAX_TOKENS_EXCEEDED","description":"Stable discriminant for this error"},"message":{"type":"string","example":"Adding these keywords re-dives the Niche for up to 10 Dive tokens, more than maxTokensUsed (0)."},"success":{"type":"boolean","example":false},"maxTokensUsed":{"type":"number","description":"The `maxTokensUsed` sent","example":0},"tokensUsed":{"type":"number","description":"The most the re-dive can cost, as a dry run reports it","example":10}},"required":["statusCode","error","message","success","maxTokensUsed","tokensUsed"]},"NicheKeywordPhraseBlockedDto":{"type":"object","properties":{"keyword":{"type":"string","example":"cheap paint by numbers"},"matchedPhrase":{"type":"string","description":"The phrase exclusion the keyword contains.","example":"cheap"}},"required":["keyword","matchedPhrase"]},"NicheKeywordsOriginBreakdownDto":{"type":"object","properties":{"alreadyInMkl":{"description":"Already in the Master Keyword List. Left untouched.","example":["diamond painting kits"],"type":"array","items":{"type":"string"}},"takenFromOutliers":{"description":"Moved into the Master Keyword List from the Outliers list. Free.","example":[],"type":"array","items":{"type":"string"}},"takenFromResidue":{"description":"Moved into the Master Keyword List from the Residue list. Free.","example":[],"type":"array","items":{"type":"string"}},"addedManually":{"description":"New to the Niche, added by hand. Their relevancy is calculated against the Niche Competitors and can be 0.","example":["paint by numbers for adults"],"type":"array","items":{"type":"string"}},"takenFromExcluded":{"description":"Matched one of the Niche's exact keyword exclusions. The exclusion was removed (not on a dry run), and the keyword is also listed in the group it landed in.","example":["diamond painting kits"],"type":"array","items":{"type":"string"}},"blockedByPhraseExclusion":{"description":"Matched one of the Niche's phrase exclusions. Not added, and listed in no other group. The rule `matchedPhrase` was left in place; remove it with POST /v1/niches/{nicheId}/keyword-exclusions/remove first to add the keyword.","example":[{"keyword":"cheap paint by numbers","matchedPhrase":"cheap"}],"type":"array","items":{"$ref":"#/components/schemas/NicheKeywordPhraseBlockedDto"}}},"required":["alreadyInMkl","takenFromOutliers","takenFromResidue","addedManually","takenFromExcluded","blockedByPhraseExclusion"]},"NicheKeywordsRefreshDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Id of the re-dive. Poll `GET /v1/niches/dives/{diveId}` with it to track progress.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the re-dive in ISO 8601 format","example":"2026-08-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"AddNicheKeywordsResponseDto":{"type":"object","properties":{"originBreakdown":{"$ref":"#/components/schemas/NicheKeywordsOriginBreakdownDto"},"tokensUsed":{"type":"number","description":"Dive tokens this call consumed, or would consume with `dryRun`. 0 while the Niche is fresh. For a stale Niche a dry run reports the number of the Niche's Competitors, the most the re-dive can cost; a real call only charges the Competitors that could still be found, so it can come in lower.","example":0},"refresh":{"description":"Present only when the Niche was stale and the add triggered a re-dive. The keywords in `addedManually` appear in the Master Keyword List once that dive succeeds.","allOf":[{"$ref":"#/components/schemas/NicheKeywordsRefreshDto"}]}},"required":["originBreakdown","tokensUsed"]},"AddNicheKeywordsRequestDto":{"type":"object","properties":{"keywords":{"description":"Keywords to add to the Niche's Master Keyword List, 100 at most and 255 characters each. They are lower-cased and trimmed and must be unique after that; blank entries are ignored.","example":["paint by numbers for adults","diamond painting kits"],"uniqueItems":true,"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}},"dryRun":{"type":"boolean","description":"When `true`, returns the same response a real call would — including `tokensUsed` — without saving anything or consuming Dive tokens. Counts towards the rate limit.","default":false},"maxTokensUsed":{"type":"number","description":"The most Dive tokens this call may consume. When adding the keywords would re-dive a stale Niche for more than this, the call fails with `error: \"MAX_TOKENS_EXCEEDED\"` and nothing is saved or charged. Pass the `tokensUsed` of a dry run to make sure the real call never costs more than you confirmed, or `0` to never pay for a re-dive. No limit when omitted.","minimum":0,"example":0}},"required":["keywords"]},"RemoveNicheKeywordsResponseDto":{"type":"object","properties":{"removedManual":{"description":"Keywords that were added by hand. Deleted from the Niche.","example":["paint by numbers for adults"],"type":"array","items":{"type":"string"}},"sentBackToOutliers":{"description":"Keywords that were moved in from Outliers. Listed under Outliers again, with their data kept.","example":[],"type":"array","items":{"type":"string"}},"sentBackToResidue":{"description":"Keywords that were moved in from Residue. Listed under Residue again, with their data kept.","example":[],"type":"array","items":{"type":"string"}},"notRemovable":{"description":"Keywords the dive found itself, or that are not in the Niche. Left unchanged.","example":["diamond painting kits"],"type":"array","items":{"type":"string"}}},"required":["removedManual","sentBackToOutliers","sentBackToResidue","notRemovable"]},"RemoveNicheKeywordsRequestDto":{"type":"object","properties":{"keywords":{"description":"Keywords to take out of the Niche's Master Keyword List, 100 at most and 255 characters each. They are lower-cased and trimmed and must be unique after that; blank entries are ignored.","example":["paint by numbers for adults"],"uniqueItems":true,"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}}},"required":["keywords"]},"ForbiddenSpacesErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"You cannot manage some of these Spaces. Nothing was changed."},"success":{"type":"boolean","example":false},"forbiddenSpaceIds":{"description":"Spaces the acting member only has view rights on","example":[34],"type":"array","items":{"type":"string"}}},"required":["statusCode","message","success","forbiddenSpaceIds"]},"UnknownTagIdsErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"message":{"type":"string","example":"Some ids are not known to your organization. Nothing was changed."},"success":{"type":"boolean","example":false},"unknownIds":{"description":"Ids that are not a Space / label of your organization","example":[999],"type":"array","items":{"type":"string"}}},"required":["statusCode","message","success","unknownIds"]},"AddNicheTagsResponseDto":{"type":"object","properties":{"added":{"type":"number","description":"Newly attached to the Niche","example":1},"alreadyPresent":{"type":"number","description":"Already attached. Left untouched, not an error.","example":1}},"required":["added","alreadyPresent"]},"NicheSpacesRequestDto":{"type":"object","properties":{"spaceIds":{"description":"Ids of the Spaces to change, from GET /v1/spaces. 1-100, unique.","example":[12,34],"uniqueItems":true,"minItems":1,"maxItems":100,"type":"array","items":{"type":"number"}}},"required":["spaceIds"]},"RemoveNicheTagsResponseDto":{"type":"object","properties":{"removed":{"type":"number","description":"Detached from the Niche","example":1},"notPresent":{"type":"number","description":"Not attached to the Niche. Left untouched, not an error.","example":1}},"required":["removed","notPresent"]},"NicheLabelsRequestDto":{"type":"object","properties":{"labelIds":{"description":"Ids of the labels to change, from GET /v1/labels. 1-100, unique.","example":[7,9],"uniqueItems":true,"minItems":1,"maxItems":100,"type":"array","items":{"type":"number"}}},"required":["labelIds"]},"ExactKeywordExclusionDto":{"type":"object","properties":{"keyword":{"type":"string","example":"dog hat"},"searchVolume":{"type":"number","description":"Search volume of the excluded keyword. 0 when the Niche has no such keyword.","example":12345}},"required":["keyword","searchVolume"]},"PhraseKeywordExclusionDto":{"type":"object","properties":{"phrase":{"type":"string","example":"puppy"},"searchVolume":{"type":"number","description":"Total search volume of the keywords this phrase hides, besides those already excluded exactly.","example":19586},"excludedKeywordsCount":{"type":"number","description":"Number of keywords this phrase hides.","example":4}},"required":["phrase","searchVolume","excludedKeywordsCount"]},"KeywordExclusionsDto":{"type":"object","properties":{"exact":{"description":"Exact exclusions, oldest first.","type":"array","items":{"$ref":"#/components/schemas/ExactKeywordExclusionDto"}},"phrase":{"description":"Phrase exclusions, oldest first.","type":"array","items":{"$ref":"#/components/schemas/PhraseKeywordExclusionDto"}}},"required":["exact","phrase"]},"KeywordExclusionEntriesDto":{"type":"object","properties":{"exact":{"example":["dog hat"],"type":"array","items":{"type":"string"}},"phrase":{"example":[],"type":"array","items":{"type":"string"}}},"required":["exact","phrase"]},"AddKeywordExclusionsResponseDto":{"type":"object","properties":{"exact":{"description":"Exact exclusions, oldest first.","type":"array","items":{"$ref":"#/components/schemas/ExactKeywordExclusionDto"}},"phrase":{"description":"Phrase exclusions, oldest first.","type":"array","items":{"$ref":"#/components/schemas/PhraseKeywordExclusionDto"}},"added":{"description":"Entries this call newly excluded.","allOf":[{"$ref":"#/components/schemas/KeywordExclusionEntriesDto"}]},"unchanged":{"description":"Entries that were already excluded. Left as is.","allOf":[{"$ref":"#/components/schemas/KeywordExclusionEntriesDto"}]}},"required":["exact","phrase","added","unchanged"]},"KeywordExclusionsRequestDto":{"type":"object","properties":{"exact":{"description":"Exact exclusions: each hides the one keyword that matches it exactly. At most 255 characters each. Entries are lower-cased and trimmed and must be unique after that; blank entries are ignored.","example":["dog hat"],"uniqueItems":true,"maxItems":100,"type":"array","items":{"type":"string"}},"phrase":{"description":"Phrase exclusions: each hides every keyword that contains the phrase, as the web app does. At most 255 characters each. Entries are lower-cased and trimmed and must be unique after that; blank entries are ignored.","example":["puppy"],"uniqueItems":true,"maxItems":100,"type":"array","items":{"type":"string"}}}},"RemoveKeywordExclusionsResponseDto":{"type":"object","properties":{"exact":{"description":"Exact exclusions, oldest first.","type":"array","items":{"$ref":"#/components/schemas/ExactKeywordExclusionDto"}},"phrase":{"description":"Phrase exclusions, oldest first.","type":"array","items":{"$ref":"#/components/schemas/PhraseKeywordExclusionDto"}},"removed":{"description":"Entries this call stopped excluding.","allOf":[{"$ref":"#/components/schemas/KeywordExclusionEntriesDto"}]},"unchanged":{"description":"Entries that were not excluded. Left as is.","allOf":[{"$ref":"#/components/schemas/KeywordExclusionEntriesDto"}]}},"required":["exact","phrase","removed","unchanged"]},"CreateRankRadarRequestDto":{"type":"object","properties":{"asin":{"type":"string","description":"The ASIN of the product to track keyword rankings for","example":"B08N5WRWNW"},"numberOfKeywords":{"type":"number","description":"Number of keywords to track in the Rank Radar. More keywords provide comprehensive tracking but consume more Search Term tokens. Minimum is 1.","example":5,"minimum":1},"nicheId":{"type":"string","description":"The Niche identifier that this Rank Radar is associated with","example":"xdGJ6gy7"},"dryRun":{"type":"boolean","description":"Preview the creation instead of performing it. Runs the same validation, the same quota check and the same duplicate check, and returns the same `warnings` — but creates no Rank Radar, consumes no Search Term tokens and writes nothing. `rankRadarId` is `null` in the response. Defaults to `false`, so omitting it creates the Rank Radar as before.","example":false,"default":false}},"required":["asin","numberOfKeywords","nicheId"]},"RankRadarWarningResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable warning code. `FAMILY_ALREADY_TRACKED` means one of your existing Rank Radars already tracks an ASIN of this variation family in this marketplace.","enum":["FAMILY_ALREADY_TRACKED"],"example":"FAMILY_ALREADY_TRACKED"},"message":{"type":"string","description":"Human-readable warning, safe to show to an end user verbatim. May contain blank-line paragraph breaks."},"existingRankRadarIds":{"description":"Ids of the existing Rank Radars this warning refers to","example":["b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"],"type":"array","items":{"type":"string"}}},"required":["code","message","existingRankRadarIds"]},"CreateRankRadarSuccessResponseDto":{"type":"object","properties":{"rankRadarId":{"type":"string","description":"Unique identifier for the created Rank Radar. Use this ID to retrieve keyword ranking data and track performance over time. `null` when `dryRun` was set, because nothing was created.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc","nullable":true},"warnings":{"description":"Non-blocking warnings about this creation. Empty when there is nothing to flag. Show them to the user as-is.","type":"array","items":{"$ref":"#/components/schemas/RankRadarWarningResponseDto"}}},"required":["rankRadarId","warnings"]},"CreateRankRadarErrorResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message describing why the Rank Radar creation failed","example":"Invalid marketplace"},"errorId":{"type":"string","description":"Unique identifier for this error instance, useful for troubleshooting and support","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"}},"required":["error","errorId"]},"InventoryByFcItemDto":{"type":"object","properties":{"fc":{"type":"string","description":"Fulfillment center code"},"state":{"type":"string","description":"State or region code where the fulfillment center is located, when known"},"availableStock":{"type":"number","description":"Units of sellable inventory currently at this fulfillment center. May be `0` when stock has run out at an FC that was previously holding this ASIN — zero-balance FCs are intentionally included."},"availableStockPercentage":{"type":"number","description":"Share of this ASIN's total sellable inventory currently at this fulfillment center, expressed as a decimal fraction between 0 and 1 (e.g. `0.075` means 7.5%). NOT a 0-to-100 percentage despite the field name."}},"required":["fc","availableStock","availableStockPercentage"]},"InventoryByFcResponseDto":{"type":"object","properties":{"asin":{"type":"string"},"sellerId":{"type":"string"},"marketplace":{"type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"lastUpdatedAt":{"type":"string","description":"Timestamp of the most recent successful refresh of live stock from the FBA Inventory API, which the stock, days-of-stock and fee fields are based on. Null if no successful refresh in the last 30 days. Before 2026-10 this field carried the distribution date, now in `distributionLastUpdatedAt`.","nullable":true,"format":"date-time"},"distributionLastUpdatedAt":{"type":"string","description":"Timestamp of the most recent successful refresh of the per-fulfillment-center `distribution`. Amazon publishes it with a delay, so it is usually up to 2 days behind `lastUpdatedAt`. Null if no successful refresh in the last 30 days.","nullable":true,"format":"date-time"},"fulfillableStock":{"type":"number","description":"Units available to ship. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"totalStock":{"type":"number","description":"All units Amazon holds or expects for this ASIN. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"reservedStock":{"type":"number","description":"Units reserved for orders, transfers or processing. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"inboundStock":{"type":"number","description":"Units on their way to Amazon (working, shipped and receiving). `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"researchingStock":{"type":"number","description":"Units Amazon is researching. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"unfulfillableStock":{"type":"number","description":"Units that cannot be sold (damaged, defective, expired). `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"daysOfStock":{"type":"number","description":"Days until the ASIN runs out of stock: Amazon's forward-looking days of supply when available, otherwise DataDive's estimate from recent sales (see `daysOfStockSource`). `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"daysOfStockSource":{"type":"string","description":"Where `daysOfStock` comes from. Also `null` when listed in `lockedFields`.","enum":["AMAZON","ESTIMATE"],"nullable":true},"daysOfStock30":{"type":"number","description":"Days of supply at the trailing 30-day sales rate. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"daysOfStock90":{"type":"number","description":"Days of supply at the trailing 90-day sales rate. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"inLowInventoryState":{"type":"boolean","description":"Whether Amazon flags the ASIN as low on inventory, which triggers the low-inventory-level fee. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing).","nullable":true},"estWeeklyLilf":{"type":"number","description":"Estimated weekly low-inventory-level fee (LILF), in `currency`. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"estLtsfNextAssessment":{"type":"number","description":"Estimated long-term storage fee (LTSF) at the next monthly assessment, in `currency`. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing). Also `null` when listed in `lockedFields`.","nullable":true},"ltsfLastMonthActual":{"type":"number","description":"Long-term storage fee Amazon charged at its latest monthly assessment, in `currency`. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing).","nullable":true},"agedUnits":{"type":"number","description":"Units Amazon will charge the aged-inventory surcharge on. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing).","nullable":true},"oldestUnitAgeDays":{"type":"number","description":"Age in days of the oldest unit. `null` when Amazon has no data for this ASIN (for example a merchant-fulfilled listing).","nullable":true},"currency":{"type":"string","description":"Currency of the fee fields (ISO 4217), the marketplace currency.","example":"USD"},"lockedFields":{"type":"array","description":"Fields your plan does not include. They are returned as `null`; upgrade to see them. Empty when nothing is locked.","items":{"type":"string","enum":["fulfillableStock","totalStock","reservedStock","inboundStock","researchingStock","unfulfillableStock","daysOfStock","daysOfStockSource","daysOfStock30","daysOfStock90","estWeeklyLilf","estLtsfNextAssessment"]}},"lockedReason":{"type":"string","description":"Why `lockedFields` are locked; `null` when nothing is locked.","enum":["PLAN_UPGRADE_REQUIRED"],"nullable":true},"totalSellableUnits":{"type":"number","description":"Total sellable units for the ASIN across all fulfillment centers"},"distribution":{"description":"Per-fulfillment-center breakdown of sellable inventory. Includes every fulfillment center currently assigned to this ASIN, including those with `availableStock: 0`. Inbound, reserved, and unsellable units are not currently broken down by fulfillment center.","type":"array","items":{"$ref":"#/components/schemas/InventoryByFcItemDto"}}},"required":["asin","sellerId","marketplace","fulfillableStock","totalStock","reservedStock","inboundStock","researchingStock","unfulfillableStock","daysOfStock","daysOfStockSource","daysOfStock30","daysOfStock90","inLowInventoryState","estWeeklyLilf","estLtsfNextAssessment","ltsfLastMonthActual","agedUnits","oldestUnitAgeDays","currency","lockedFields","lockedReason","totalSellableUnits","distribution"]},"IndexingIssueAlertDto":{"type":"object","properties":{"id":{"type":"number","example":12345,"description":"Unique alert identifier"},"asin":{"type":"string","example":"B0ABCDEFGH","description":"The ASIN that is no longer indexed for its tracked keywords"},"title":{"type":"object","example":"Wireless Earbuds, Bluetooth 5.3","nullable":true},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true},"isParent":{"type":"boolean","example":false,"description":"True when the ASIN is a parent of a variation family"},"sellerId":{"type":"string","example":"A1B2C3D4E5"},"marketplace":{"type":"string","example":"com"},"lastAlertedAt":{"format":"date-time","type":"string","example":"2024-06-01T12:00:00Z","description":"When the alert was surfaced (its creation time). Each time an alert re-fires, a fresh card is created, so this always reflects the most recent surfacing."},"resolvedAt":{"type":"object","example":null,"nullable":true,"description":"When the alert was resolved, or null if still active"}},"required":["id","asin","title","imageUrl","isParent","sellerId","marketplace","lastAlertedAt","resolvedAt"]},"IndexingIssueAlertListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/IndexingIssueAlertDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"BlindSpendSearchTermDto":{"type":"object","properties":{"term":{"type":"string","example":"wireless earbuds bluetooth","description":"The customer search term that wasted spend"},"spend":{"type":"object","example":123.45,"nullable":true,"description":"Ad spend on this search term"},"sales":{"type":"object","example":0,"nullable":true,"description":"Attributed sales from this search term"},"clicks":{"type":"object","example":15,"nullable":true},"cvr":{"type":"object","example":0,"nullable":true,"description":"Conversion rate (0–1)"},"impressions":{"type":"object","example":1500,"nullable":true}},"required":["term","spend","sales","clicks","cvr","impressions"]},"BlindSpendAlertDto":{"type":"object","properties":{"id":{"type":"number","example":12345,"description":"Unique alert identifier"},"asin":{"type":"object","example":"B0ABCDEFGH","nullable":true},"title":{"type":"object","example":"Wireless Earbuds, Bluetooth 5.3","nullable":true},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true},"sellerId":{"type":"string","example":"A1B2C3D4E5"},"marketplace":{"type":"string","example":"com"},"lastAlertedAt":{"format":"date-time","type":"string","example":"2024-06-01T12:00:00Z","description":"When the alert was surfaced (its creation time). Each time an alert re-fires, a fresh card is created, so this always reflects the most recent surfacing."},"resolvedAt":{"type":"object","example":null,"nullable":true,"description":"When the alert was resolved, or null if still active"},"wastedSpend":{"type":"number","example":246.9,"description":"Total ad spend across the unresolved wasted-spend search terms"},"totalKeywordCount":{"type":"number","example":8,"description":"Total number of search terms in this alert"},"unresolvedKeywordCount":{"type":"number","example":5,"description":"Number of search terms still unresolved"},"searchTerms":{"description":"The unresolved wasted-spend search terms","type":"array","items":{"$ref":"#/components/schemas/BlindSpendSearchTermDto"}}},"required":["id","asin","title","imageUrl","sellerId","marketplace","lastAlertedAt","resolvedAt","wastedSpend","totalKeywordCount","unresolvedKeywordCount","searchTerms"]},"BlindSpendAlertListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/BlindSpendAlertDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"SellerProfileDto":{"type":"object","properties":{"sellerId":{"type":"string","example":"A1B2C3D4E5","description":"Amazon seller profile identifier"},"sellerName":{"type":"string","example":"My Brand Store","description":"Display name of the seller profile"},"marketplace":{"type":"string","example":"com","description":"Amazon marketplace domain (e.g. com, co.uk, de, ca)"},"hasAdApi":{"type":"boolean","example":true,"description":"Whether this seller profile has Ad API credentials connected"},"createdAt":{"format":"date-time","type":"string","description":"When the seller profile was connected to DataDive"}},"required":["sellerId","sellerName","marketplace","hasAdApi","createdAt"]},"SellerProfileListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/SellerProfileDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"CatalogAsinDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0ABCDEFGH","description":"Amazon Standard Identification Number"},"title":{"type":"string","example":"Wireless Earbuds, Bluetooth 5.3","description":"Product title"},"parentAsin":{"type":"object","example":"B0AAAA0000","nullable":true,"description":"Parent ASIN if this is a child variation"},"brand":{"type":"object","example":"Anker","nullable":true,"description":"Product brand"},"status":{"type":"string","example":"Active","description":"Product listing status"},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true,"description":"Main product image URL"},"hasVariations":{"type":"object","example":true,"nullable":true,"description":"Whether the product has variations"}},"required":["asin","title","parentAsin","brand","status","imageUrl","hasVariations"]},"CatalogAsinListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/CatalogAsinDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ListingChangeCorrelationDto":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNAVAILABLE_NO_ACTIVE_RANK_RADAR","UNAVAILABLE"],"description":"Status of correlation data availability"},"message":{"type":"object","nullable":true,"description":"Human-readable status message"},"salesCvr":{"type":"object","nullable":true,"description":"Sales conversion rate before/after the change","example":{"before":0.12,"after":0.15}},"top10SearchTerms":{"type":"object","nullable":true,"description":"Count of tracked keywords in top 10 organic rank before/after","example":{"before":5,"after":8}},"top50SearchTerms":{"type":"object","nullable":true,"description":"Count of tracked keywords in top 50 organic rank before/after","example":{"before":12,"after":18}}},"required":["status","message","salesCvr","top10SearchTerms","top50SearchTerms"]},"ListingChangeExternalItemDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0ABCDEFGH"},"title":{"type":"object","example":"Wireless Earbuds, Bluetooth 5.3","nullable":true},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true},"date":{"format":"date-time","type":"string","description":"When the change was first detected"},"type":{"type":"string","enum":["Price","Content","Image"]},"contentType":{"type":"object","description":"Content sub-type (only for Content changes)","nullable":true,"example":"Title"},"description":{"type":"string","description":"Human-readable description of the change"},"previousValue":{"type":"object","nullable":true,"description":"Previous value (formatted)"},"newValue":{"type":"object","nullable":true,"description":"New value (formatted)"},"possibleAiRewrite":{"type":"object","nullable":true,"description":"True when this title change matches the pattern of an Amazon-initiated AI rewrite for 75-char compliance"},"flagNote":{"type":"object","nullable":true,"description":"Note explaining the flag, when present"},"correlation":{"nullable":true,"description":"Metric correlation data","type":"object","allOf":[{"$ref":"#/components/schemas/ListingChangeCorrelationDto"}]}},"required":["asin","title","imageUrl","date","type","contentType","description","previousValue","newValue","possibleAiRewrite","flagNote","correlation"]},"ListingChangesExternalListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/ListingChangeExternalItemDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"CampaignBudgetDto":{"type":"object","properties":{"type":{"type":"object","nullable":true},"amount":{"type":"object","nullable":true},"currencyCode":{"type":"object","nullable":true}},"required":["type","amount","currencyCode"]},"PlacementMetricsDto":{"type":"object","properties":{"bidAdjustment":{"type":"object","nullable":true},"impressions":{"type":"number"},"clicks":{"type":"number"},"ctr":{"type":"object","nullable":true},"cpc":{"type":"object","nullable":true},"spend":{"type":"number"},"unitsSold":{"type":"number"},"orders":{"type":"number","description":"Purchases (14-day click attribution)"},"cvr":{"type":"object","nullable":true,"description":"Orders / clicks"},"sales":{"type":"number"},"acos":{"type":"object","nullable":true},"roas":{"type":"object","nullable":true,"description":"Sales / spend"}},"required":["bidAdjustment","impressions","clicks","ctr","cpc","spend","unitsSold","orders","cvr","sales","acos","roas"]},"CampaignPlacementsDto":{"type":"object","properties":{"topOfSearch":{"$ref":"#/components/schemas/PlacementMetricsDto"},"restOfSearch":{"$ref":"#/components/schemas/PlacementMetricsDto"},"productPage":{"$ref":"#/components/schemas/PlacementMetricsDto"},"offAmazon":{"$ref":"#/components/schemas/PlacementMetricsDto"},"homePageBidAdjustment":{"type":"object","nullable":true}},"required":["topOfSearch","restOfSearch","productPage","offAmazon","homePageBidAdjustment"]},"PpcCampaignDto":{"type":"object","properties":{"campaignId":{"type":"number"},"name":{"type":"string"},"type":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"],"nullable":true},"state":{"type":"string"},"targetingType":{"type":"string","enum":["MANUAL","AUTO","T00020","T00030"],"nullable":true},"bidStrategy":{"type":"object","nullable":true},"budget":{"$ref":"#/components/schemas/CampaignBudgetDto"},"impressions":{"type":"number"},"clicks":{"type":"number"},"ctr":{"type":"object","nullable":true},"cpc":{"type":"object","nullable":true},"cvr":{"type":"object","nullable":true,"description":"Orders / clicks"},"spend":{"type":"number"},"unitsSold":{"type":"number"},"orders":{"type":"number"},"sales":{"type":"number"},"tosImpressionShare":{"type":"object","nullable":true},"acos":{"type":"object","nullable":true},"roas":{"type":"object","nullable":true},"tacos":{"type":"object","nullable":true},"asinCount":{"type":"number"},"placements":{"$ref":"#/components/schemas/CampaignPlacementsDto"}},"required":["campaignId","name","type","state","targetingType","bidStrategy","budget","impressions","clicks","ctr","cpc","cvr","spend","unitsSold","orders","sales","tosImpressionShare","acos","roas","tacos","asinCount"]},"PpcCampaignsExternalListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/PpcCampaignDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"FastKeywordsRunResponseDto":{"type":"object","properties":{"fastKeywordsId":{"type":"number","description":"Id of the Fast Keywords result. Poll GET /v1/fast-keywords/{fastKeywordsId} with it.","example":8052},"requestId":{"type":"number","description":"Id of this request","example":12011},"status":{"type":"string","description":"`success` right away when a fresh result for the same product already exists","enum":["in-progress","failed","success"],"example":"in-progress"},"tokenCost":{"type":"number","description":"Dive tokens this call consumed","example":1},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp in ISO 8601 format","example":"2026-10-22T10:05:00.000Z"}},"required":["fastKeywordsId","requestId","status","tokenCost","estimatedCompletionDate"]},"FastKeywordsRunPreviewResponseDto":{"type":"object","properties":{"tokenCost":{"type":"number","description":"Dive tokens the call would consume","example":1},"hasEnoughTokens":{"type":"boolean","description":"Whether your organization has enough Dive tokens left","example":true}},"required":["tokenCost","hasEnoughTokens"]},"RunFastKeywordsRequestDto":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"Check eligibility and Dive tokens without running anything or spending a token","example":false},"marketplace":{"type":"string","description":"The Amazon marketplace where the product is listed","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"asin":{"type":"string","description":"The ASIN to find keywords for","example":"B08N5WRWNW"}},"required":["marketplace","asin"]},"RefreshFastKeywordsRequestDto":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"Check eligibility and Dive tokens without running anything or spending a token","example":false}}},"FastKeywordsRefreshConflictResponseDto":{"type":"object","properties":{"statusCode":{"type":"number","example":409},"error":{"type":"string","enum":["IN_PROGRESS","COOLDOWN"],"example":"COOLDOWN"},"message":{"type":"string","example":"This Fast Keywords result can only be updated once every 24 hours. Next eligible at 2026-10-23T09:00:00.000Z"},"success":{"type":"boolean","example":false},"nextEligibleAt":{"type":"string","description":"When the result can be refreshed again. null while a run is in progress.","nullable":true,"example":"2026-10-23T09:00:00.000Z"}},"required":["statusCode","error","message","success","nextEligibleAt"]},"ExternalTagNodeDto":{"type":"object","properties":{"id":{"type":"number","example":102,"description":"Id to pass to the niche assignment routes and the list filters"},"name":{"type":"string","example":"Dog Hats","description":"Name of this node only"},"path":{"type":"string","example":"Pet Friends/Dog Hats","description":"Full name, with ancestors joined by `/`"},"parentId":{"type":"number","example":101,"nullable":true,"description":"Id of the parent node in this tree, or null at the top level"},"children":{"example":[],"type":"array","items":{"$ref":"#/components/schemas/ExternalTagNodeDto"}}},"required":["id","name","path","parentId","children"]},"ExternalTagTreeDto":{"type":"object","properties":{"data":{"example":[{"id":101,"name":"Pet Friends","path":"Pet Friends","parentId":null,"children":[{"id":102,"name":"Dog Hats","path":"Pet Friends/Dog Hats","parentId":101,"children":[]}]}],"type":"array","items":{"$ref":"#/components/schemas/ExternalTagNodeDto"}}},"required":["data"]},"ExternalQuotaFeatureDto":{"type":"object","properties":{"used":{"type":"object","example":42,"nullable":true,"description":"Current usage count"},"capacity":{"type":"object","example":250,"nullable":true,"description":"Quota capacity"}},"required":["used","capacity"]},"ExternalQuotaFeaturesDto":{"type":"object","properties":{"DIVED_ASINS":{"description":"Dive token usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"RANK_RADAR_KEYWORDS":{"description":"Rank Radar tracked keywords usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"PRODUCT_BRIEF_ASINS":{"description":"Product brief usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"AI_COPYWRITER_PROMPTS":{"description":"AI Copywriter prompt usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"INDEXING_DIAGNOSIS":{"description":"Indexing diagnosis usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"REVIEW_REQUEST_ASINS":{"description":"ASINs selected for automated review requests","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]}},"required":["DIVED_ASINS","RANK_RADAR_KEYWORDS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","INDEXING_DIAGNOSIS","REVIEW_REQUEST_ASINS"]},"ExternalQuotaResponseDto":{"type":"object","properties":{"nextRefreshDate":{"type":"object","example":"2024-04-15T00:00:00.000Z","nullable":true,"description":"ISO 8601 timestamp of next quota reset"},"features":{"description":"Usage info per billable feature","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeaturesDto"}]}},"required":["nextRefreshDate","features"]},"ExternalUsageLogDto":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"John Doe","description":"Name of the user who performed the action"},"email":{"type":"string","example":"johndoe@example.com","description":"Email of the user who performed the action"},"qty":{"type":"number","example":1,"description":"Number of tokens consumed"},"type":{"type":"string","enum":["DIVED_ASINS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","RANK_RADAR_KEYWORDS","INDEXING_DIAGNOSIS","REVIEW_REQUEST_ASINS"],"description":"The billable feature type"},"action":{"type":"string","enum":["RANK_RADAR_PAUSE","RANK_RADAR_CREATE","RANK_RADAR_UPDATE","RANK_RADAR_RESUMED","RANK_RADAR_ARCHIVE","RANK_RADAR_KEYWORD_PAUSE","RANK_RADAR_KEYWORD_UNPAUSE","DIVE_SCHEDULED","DIVE_DIVEBOX","SOLO_REVERSE_ASIN","REFUND_FAILED_SOLO_REVERSE_ASIN","REFUND_FAILED_DIVE","ANALYZE_COMPETITORS","ANALYZE_COMPETITORS_FAILED","INDEXING_DIAGNOSIS","INDEXING_DIAGNOSIS_FAILED","AI_GENERATE_DESCRIPTION","AI_GENERATE_BULLETS","AI_GENERATE_ITEM_HIGHLIGHTS","AI_GENERATE_LISTING","AI_GENERATE_LISTING_FAILED","MANUAL_KEYWORD_ADD","MANUAL_KEYWORD_REMOVE"],"nullable":true,"description":"Specific action performed"},"nicheId":{"type":"string","nullable":true,"example":"boGkBnlEx4","description":"Associated Niche identifier"},"nicheName":{"type":"string","nullable":true,"example":"dog hat","description":"Associated Niche name"},"rankRadarId":{"type":"string","nullable":true,"example":"5231a9af-82f2-4c87-9ed4-cef0447cff1e","description":"Associated Rank Radar identifier"},"date":{"type":"string","format":"date-time","description":"When the usage was recorded"}},"required":["name","email","qty","type","action","nicheId","nicheName","rankRadarId","date"]},"ExternalUsageLogListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/ExternalUsageLogDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"FastKeywordsListItemDto":{"type":"object","properties":{"fastKeywordsId":{"type":"number","example":8052},"asin":{"type":"string","example":"B08N5WRWNW"},"parentAsin":{"type":"string","nullable":true,"example":"B08N5WRWNV"},"marketplace":{"type":"string","example":"com"},"status":{"type":"string","enum":["in-progress","failed","success"],"example":"success"},"title":{"type":"string","nullable":true,"example":"Knit Dog Hat with Ear Holes"},"brand":{"type":"string","nullable":true,"example":"Pawsome"},"price":{"type":"number","nullable":true,"example":14.99},"keywordCount":{"type":"number","example":1240},"totalSearchVolume":{"type":"number","nullable":true,"example":310500},"top10OrganicRankCount":{"type":"number","nullable":true,"example":85},"rootCount":{"type":"number","nullable":true,"example":42},"lastRefreshedAt":{"type":"string","nullable":true,"example":"2026-10-22T09:00:00.000Z"},"requestedAt":{"type":"string","description":"Latest request by anyone in your organization","example":"2026-10-22T08:58:00.000Z"}},"required":["fastKeywordsId","asin","parentAsin","marketplace","status","title","brand","price","keywordCount","totalSearchVolume","top10OrganicRankCount","rootCount","lastRefreshedAt","requestedAt"]},"FastKeywordsListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/FastKeywordsListItemDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"FastKeywordsProductDto":{"type":"object","properties":{"title":{"type":"string","nullable":true,"example":"Knit Dog Hat with Ear Holes"},"imageUrl":{"type":"string","nullable":true,"example":"https://m.media-amazon.com/images/I/71example.jpg"},"brand":{"type":"string","nullable":true,"example":"Pawsome"},"price":{"type":"number","nullable":true,"example":14.99}},"required":["title","imageUrl","brand","price"]},"FastKeywordsVariationDto":{"type":"object","properties":{"asin":{"type":"string","example":"B08N5WRWNX"},"title":{"type":"string","nullable":true,"example":"Knit Dog Hat, Red"},"imageUrl":{"type":"string","nullable":true,"example":"https://m.media-amazon.com/images/I/71example.jpg"}},"required":["asin","title","imageUrl"]},"FastKeywordsRootDto":{"type":"object","properties":{"root":{"type":"string","example":"dog hat"},"aggregateSearchVolume":{"type":"number","description":"Search volume of every keyword under this root","example":48200},"medianOrganicRank":{"type":"number","nullable":true,"description":"null when none rank organically","example":7},"keywords":{"example":["dog hat","dog hats for small dogs"],"type":"array","items":{"type":"string"}}},"required":["root","aggregateSearchVolume","medianOrganicRank","keywords"]},"FastKeywordsCompetitorDto":{"type":"object","properties":{"asin":{"type":"string","example":"B07XJ8C8F5"},"title":{"type":"string","nullable":true,"example":"Dog Winter Hat"},"imageUrl":{"type":"string","nullable":true,"example":"https://m.media-amazon.com/images/I/61example.jpg"},"variationCount":{"type":"number","example":3}},"required":["asin","title","imageUrl","variationCount"]},"FastKeywordsResultDto":{"type":"object","properties":{"fastKeywordsId":{"type":"number","example":8052},"status":{"type":"string","enum":["in-progress","failed","success"],"example":"success"},"asin":{"type":"string","example":"B08N5WRWNW"},"parentAsin":{"type":"string","nullable":true,"example":"B08N5WRWNV"},"marketplace":{"type":"string","example":"com"},"product":{"$ref":"#/components/schemas/FastKeywordsProductDto"},"variations":{"type":"array","items":{"$ref":"#/components/schemas/FastKeywordsVariationDto"}},"roots":{"description":"Ordered by aggregate search volume, highest first","type":"array","items":{"$ref":"#/components/schemas/FastKeywordsRootDto"}},"competitors":{"description":"Top 10 Competitors by keyword overlap","type":"array","items":{"$ref":"#/components/schemas/FastKeywordsCompetitorDto"}},"keywordCount":{"type":"number","description":"Read them with GET /v1/fast-keywords/{fastKeywordsId}/keywords","example":1240},"lastRefreshedAt":{"format":"date-time","type":"string","nullable":true,"example":"2026-10-22T09:00:00.000Z"},"failureReason":{"type":"string","enum":["no-keyword-data","asin-not-found","external-data-unavailable","unknown"],"description":"Set when `status` is `failed`"},"failureMessage":{"type":"string","description":"Why the run failed, or why a successful run has little to show. Safe to show to a user."},"insufficientKeywordData":{"type":"boolean","description":"true when a successful run found too few keywords to be useful"}},"required":["fastKeywordsId","status","asin","parentAsin","marketplace","product","variations","roots","competitors","keywordCount","lastRefreshedAt"]},"FastKeywordsKeywordDto":{"type":"object","properties":{"keyword":{"type":"string","example":"dog hat"},"searchVolume":{"type":"number","nullable":true,"example":12400},"organicRank":{"type":"number","nullable":true,"example":4},"sponsoredRank":{"type":"number","nullable":true,"example":null}},"required":["keyword","searchVolume","organicRank","sponsoredRank"]},"FastKeywordsKeywordListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"Ordered by search volume, highest first","type":"array","items":{"$ref":"#/components/schemas/FastKeywordsKeywordDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"NicheDiveStatusSuccessResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier of the Dive process","example":"xxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["in_progress","error","success"],"description":"Current status of the Dive: in_progress (analysis ongoing), success (completed successfully), or error (failed)","example":"in_progress"},"nicheId":{"type":"string","description":"Unique identifier of the created Niche. Use this to access the Niche research data via other endpoints.","example":"HdNCcryRCs"},"tokensUsed":{"type":"number","description":"Number of Dive tokens consumed by this Niche analysis","example":30},"tokensLeft":{"type":"number","description":"Remaining Dive tokens available for future dives","example":1000}},"required":["diveId","status","nicheId","tokensUsed","tokensLeft"]},"NicheDiveStatusInProgressResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier of the Dive process","example":"xxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["in_progress","error","success"],"description":"Current status of the Dive: in_progress (analysis ongoing), success (completed successfully), or error (failed)","example":"in_progress"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the Niche Dive in ISO 8601 format","example":"2024-04-01T00:00:00Z"}},"required":["diveId","status","estimatedCompletionDate"]},"NicheDiveStatusErrorResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier of the Dive process","example":"xxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["in_progress","error","success"],"description":"Current status of the Dive: in_progress (analysis ongoing), success (completed successfully), or error (failed)","example":"in_progress"},"error":{"type":"string","description":"Error message describing what went wrong during the Dive analysis","example":"Some error message"}},"required":["diveId","status","error"]},"PpcAlertSearchTermDto":{"type":"object","properties":{"search_term":{"type":"string","example":"yoga mat thick"},"label":{"type":"string","example":"blindspend"},"spend":{"type":"object","example":45.5},"sales":{"type":"object","example":0},"clicks":{"type":"object","example":30},"impressions":{"type":"object","example":500},"cvr":{"type":"object","example":0},"roas":{"type":"object","example":0},"competitor_cvr":{"type":"object","example":0.08},"search_volume":{"type":"object","example":12000},"impression_rank":{"type":"object","example":5},"impression_share":{"type":"object","example":0.12}},"required":["search_term","label"]},"PpcAlertDataDto":{"type":"object","properties":{"seller_id":{"type":"string","example":"A1B2C3D4E5F6G7"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"tracked_asin":{"type":"string","example":"B0EXAMPLE1"},"tracked_asin_title":{"type":"object","example":"Yoga Mat - Extra Thick"},"niche_label":{"type":"string","example":"Yoga Mats"},"rank_radar_id":{"type":"string","example":"11111111-2222-4333-aaaa-bbbbbbbbbbbb"},"return_url":{"type":"string","example":"https://2.datadive.tools/alerts"},"search_terms":{"type":"array","items":{"$ref":"#/components/schemas/PpcAlertSearchTermDto"}},"search_term_count":{"type":"number","example":2},"total_spend":{"type":"number","example":67.5}},"required":["seller_id","marketplace","tracked_asin","niche_label","rank_radar_id","return_url","search_terms","search_term_count","total_spend"]},"PotentialWastedSpendPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.potential_wasted_spend"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/PpcAlertDataDto"}},"required":["id","type","created_at","organization_id","data"]},"GrowthOpportunityPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.growth_opportunity"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/PpcAlertDataDto"}},"required":["id","type","created_at","organization_id","data"]},"ProfitableOutOfBudgetTargetDataDto":{"type":"object","properties":{"targeting":{"type":"string","example":"yoga mat thick"},"keyword":{"type":"object","example":"yoga mat thick"},"match_type":{"type":"object","example":"EXACT"},"spend":{"type":"object","example":80},"sales":{"type":"object","example":440},"roas":{"type":"object","example":5.5}},"required":["targeting"]},"ProfitableOutOfBudgetDataDto":{"type":"object","properties":{"seller_id":{"type":"string","example":"A1B2C3D4E5F6G7"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"tracked_asin":{"type":"string","example":"B0EXAMPLE1"},"tracked_asin_title":{"type":"object","example":"Yoga Mat - Extra Thick"},"niche_label":{"type":"string","example":"Yoga Mats"},"rank_radar_id":{"type":"string","example":"11111111-2222-4333-aaaa-bbbbbbbbbbbb"},"return_url":{"type":"string","example":"https://2.datadive.tools/alerts"},"campaign_id":{"type":"string","example":"123456789012345"},"campaign_name":{"type":"object","example":"Yoga Mats | SP | Auto"},"recurring_after_budget_increase":{"type":"boolean","example":false},"previous_budget_increased_at":{"type":"object","example":"2026-05-01T00:00:00.000Z"},"roas":{"type":"object","example":5.2},"budget":{"type":"object","example":50},"spend":{"type":"object","example":120.5},"sales":{"type":"object","example":626.6},"out_of_budget_days":{"type":"number","example":3},"out_of_budget_window_days":{"type":"number","example":3},"targets":{"type":"array","items":{"$ref":"#/components/schemas/ProfitableOutOfBudgetTargetDataDto"}},"target_count":{"type":"number","example":2}},"required":["seller_id","marketplace","tracked_asin","niche_label","rank_radar_id","return_url","campaign_id","recurring_after_budget_increase","out_of_budget_days","out_of_budget_window_days","targets","target_count"]},"ProfitableOutOfBudgetPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.profitable_out_of_budget"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/ProfitableOutOfBudgetDataDto"}},"required":["id","type","created_at","organization_id","data"]},"IndexingIssueDataDto":{"type":"object","properties":{"seller_id":{"type":"string","example":"A1B2C3D4E5F6G7"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"tracked_asin":{"type":"string","example":"B0EXAMPLE1"},"tracked_asin_title":{"type":"object","example":"Yoga Mat - Extra Thick"},"niche_label":{"type":"string","example":"Yoga Mats"},"rank_radar_id":{"type":"string","example":"11111111-2222-4333-aaaa-bbbbbbbbbbbb"},"return_url":{"type":"string","example":"https://2.datadive.tools/alerts"},"is_parent":{"type":"boolean","example":true}},"required":["seller_id","marketplace","tracked_asin","niche_label","rank_radar_id","return_url","is_parent"]},"IndexingIssuePayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.indexing_issue"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/IndexingIssueDataDto"}},"required":["id","type","created_at","organization_id","data"]},"CompetitorPromotionDataDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0COMPETITOR"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"competitor_title":{"type":"object","example":"Premium Yoga Mat - Extra Thick"},"old_price":{"type":"number","example":2999},"new_price":{"type":"number","example":1999},"change_percentage":{"type":"number","example":-33.3},"deal_type":{"type":"object","example":"LIMITED_TIME_DEAL"},"access_type":{"type":"object","example":"PRIME_EXCLUSIVE"},"promotion_starts_at":{"type":"object","example":"2026-06-01T00:00:00.000Z"},"promotion_ends_at":{"type":"object","example":"2026-06-07T23:59:59.000Z"}},"required":["asin","marketplace","old_price","new_price","change_percentage"]},"CompetitorPromotionPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.competitor_promotion"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/CompetitorPromotionDataDto"}},"required":["id","type","created_at","organization_id","data"]},"CompetitorPriceDropDataDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0COMPETITOR"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"competitor_title":{"type":"object","example":"Premium Yoga Mat - Extra Thick"},"old_price":{"type":"number","example":2999},"new_price":{"type":"number","example":2399},"change_percentage":{"type":"number","example":-20}},"required":["asin","marketplace","old_price","new_price","change_percentage"]},"CompetitorPriceDropPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.competitor_price_drop"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/CompetitorPriceDropDataDto"}},"required":["id","type","created_at","organization_id","data"]}}},"webhooks":{"alert.potential_wasted_spend":{"post":{"summary":"Potential Wasted Spend","description":"Spending on a keyword you should stop bidding on","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PotentialWastedSpendPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.growth_opportunity":{"post":{"summary":"Growth Opportunity","description":"Spending on a keyword you should start tracking","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrowthOpportunityPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.profitable_out_of_budget":{"post":{"summary":"Profitable Campaign Out of Budget","description":"A profitable campaign repeatedly ran out of budget","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfitableOutOfBudgetPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.indexing_issue":{"post":{"summary":"Indexing Issue","description":"ASIN not indexed for a keyword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexingIssuePayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.competitor_promotion":{"post":{"summary":"Competitor Promotion","description":"Competitor promotion detected","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorPromotionPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.competitor_price_drop":{"post":{"summary":"Competitor Price Drop","description":"Competitor price drop detected","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorPriceDropPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}}}}