Catalog
Products and everything that describes them. Requires catalog:read.
Servers
List the authenticated account's products
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Case-insensitive substring match over the product title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.
1200Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Responses
200
GET /v1/products/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
amazon-seller-products
The authenticated account's Amazon Seller Central product listings. Requires catalog:read.
List the authenticated account's Amazon seller products
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.
1200Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Responses
200
GET /v1/amazon-seller-products/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
amazon-vendor-products
The authenticated account's Amazon Vendor Central product listings. Requires catalog:read.
List the authenticated account's Amazon vendor products
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.
1200Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Responses
200
GET /v1/amazon-vendor-products/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
amazon-advertising-products
The authenticated account's Amazon advertising products. Requires catalog:read.
List the authenticated account's Amazon advertising products
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.
1200Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Responses
200
GET /v1/amazon-advertising-products/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
seller-product-metrics
Seller Central sales and traffic per product, aggregated from the account's report history. Requires catalog:read.
Operations
Seller Central sales and traffic per product, from the account's report history
Aggregated from the report history over a required start_date/end_date window, grouped by ASIN + SKU + connection + country + currency (the same ASIN sells in several marketplaces with different prices and currencies). Unlike the rest of the API, this resource paginates with limit/offset (an aggregated row has no id to use as a cursor) and has_more tells whether another page follows. Monetary amounts are decimal strings. sessions, page_views, buy_box_percentage, conversion_rate and rank are null, never 0, when Amazon did not report them: its traffic report only covers products with activity. conversion_rate is orders / sessions here, not orders / clicks as in campaign_metrics. The economics block (referral_fee, fba_fulfilment_fee, storage_fee, other_fees, amazon_fees, net_sales, net_units, margin_before_ads, refunded_sales, refunded_units) comes from Amazon Data Kiosk and has three caveats: every amount excludes VAT, as sales does, but it comes from a different Amazon source, so net_sales does not reconcile exactly with sales minus refunds; storage fees are booked on a single day of the month, so read margins over at least a month; and refunds are booked on the refund date, not the sale date. It is null when there is no economics data for the product in the window (it lands 48-72 h late). No field in it includes advertising: take ad spend from the advertising metrics. For that reason margin_before_ads is higher than the product margin shown in the Epinium app, which also subtracts the ad spend Amazon attributes to the product. With group_by, rows are aggregated across products (see the parameter): sums are summed, stock is the sum of the latest stock of each product, days_of_coverage is recomputed on the aggregates (stock summed over the products that reported it, units over all of them), buy_box_percentage and b2b_buy_box_percentage are weighted by page views, and rank, price and fulfillment_channel are null. total_count then counts groups, or group-periods when granularity is not total.
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularity — daily allows a much shorter span than total, and target-metrics and search-term-metrics are stricter than the rest because limit/offset bound the response but not what ClickHouse scans. Going over returns a 400 naming the exact limit for your request.
"2026-07-01""^\\d{4}-\\d{2}-\\d{2}$"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularity — daily allows a much shorter span than total, and target-metrics and search-term-metrics are stricter than the rest because limit/offset bound the response but not what ClickHouse scans. Going over returns a 400 naming the exact limit for your request.
"2026-07-31""^\\d{4}-\\d{2}-\\d{2}$"total (default) aggregates the whole window into one row per entity or group. Any other value adds a date field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: 2026-01-15..2026-03-10 with monthly returns January (15th to 31st), February, and March (1st to 10th). daily has a shorter window cap than the rest.
"total""daily""weekly""monthly""quarterly""yearly""total""total"Page size. For a top-N, combine order_by with a small limit instead of raising it: limit/offset bound the response, not what ClickHouse scans.
100100110000009007199254740991"asc""desc""desc""desc"Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when granularity is not total), and the credits scale with the groups returned, not with the number of products. account collapses everything and cannot be combined with other values; connection and country can be combined by repeating the param (group_by[]=connection&group_by[]=country). Rows are always split by currency (amounts are never converted) and, in advertising, by ad_product. In grouped rows the entity fields (product, asin, sku, campaign, ad_group, target...) are null, and so are the metrics that cannot be aggregated (rank, price, fulfillment_channel, vendor rates and sourcing_lead_time_days). Seller stock and days_of_coverage are null too unless country is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. cluster gives one row per product cluster (the clusters resource), with its id in cluster and its name in cluster_name. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with connection and country, and with the cluster filter to choose which clusters come back.
Restrict the rows to the products of one or more product clusters (the clusters resource), by cluster id; repeat the param for several (cluster[]=a&cluster[]=b) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with group_by (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Amazon ASIN: 10 uppercase letters or digits, e.g. B08GPHNSCW.
"^[A-Z0-9]{10}$""sales""units""orders""sessions""page_views""rank""conversion_rate""net_sales""amazon_fees""margin_before_ads""days_of_coverage""b2b_sales"Responses
200
vendor-product-metrics
Vendor Central sales per product, split by manufacturing and sourcing, aggregated from the account's report history. Requires catalog:read.
Operations
Vendor Central sales per product, split by manufacturing and sourcing, from the account's report history
Aggregated from the report history over a required start_date/end_date window, grouped by ASIN + connection + country + currency (the same ASIN sells in several marketplaces with different prices and currencies; the SKU is not part of the key here, unlike seller_product_metrics). Unlike the rest of the API, this resource paginates with limit/offset (an aggregated row has no id to use as a cursor) and has_more tells whether another page follows. Monetary amounts are decimal strings. There is deliberately NO single sales field: Vendor Central has two business models and Amazon does not report them symmetrically. Manufacturing (Amazon makes the product under licence) reports ordered, shipped and net received, while sourcing (you sell wholesale to Amazon) reports only shipped and net received. Read the pair that matches how you sell. Vendor has no sessions or conversion rate at all; glance_views is the traffic metric, and it is null, never 0, when Amazon did not report it, as are rank and both *_sellable_units. The *_sellable_units fields are the latest inventory snapshot in the window, not a sum. With group_by, rows are aggregated across products (see the parameter): sums are summed, the snapshot fields (both *_sellable_units and the other levels read on the last day of the window with data) are the sum of the latest value of each product, days_of_coverage is recomputed on the aggregates (stock summed over the products that reported it, units over all of them), and rank, sourcing_lead_time_days and the sourcing rates are null. total_count then counts groups, or group-periods when granularity is not total.
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularity — daily allows a much shorter span than total, and target-metrics and search-term-metrics are stricter than the rest because limit/offset bound the response but not what ClickHouse scans. Going over returns a 400 naming the exact limit for your request.
"2026-07-01""^\\d{4}-\\d{2}-\\d{2}$"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularity — daily allows a much shorter span than total, and target-metrics and search-term-metrics are stricter than the rest because limit/offset bound the response but not what ClickHouse scans. Going over returns a 400 naming the exact limit for your request.
"2026-07-31""^\\d{4}-\\d{2}-\\d{2}$"total (default) aggregates the whole window into one row per entity or group. Any other value adds a date field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: 2026-01-15..2026-03-10 with monthly returns January (15th to 31st), February, and March (1st to 10th). daily has a shorter window cap than the rest.
"total""daily""weekly""monthly""quarterly""yearly""total""total"Page size. For a top-N, combine order_by with a small limit instead of raising it: limit/offset bound the response, not what ClickHouse scans.
100100110000009007199254740991"asc""desc""desc""desc"Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when granularity is not total), and the credits scale with the groups returned, not with the number of products. account collapses everything and cannot be combined with other values; connection and country can be combined by repeating the param (group_by[]=connection&group_by[]=country). Rows are always split by currency (amounts are never converted) and, in advertising, by ad_product. In grouped rows the entity fields (product, asin, sku, campaign, ad_group, target...) are null, and so are the metrics that cannot be aggregated (rank, price, fulfillment_channel, vendor rates and sourcing_lead_time_days). Seller stock and days_of_coverage are null too unless country is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. cluster gives one row per product cluster (the clusters resource), with its id in cluster and its name in cluster_name. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with connection and country, and with the cluster filter to choose which clusters come back.
Restrict the rows to the products of one or more product clusters (the clusters resource), by cluster id; repeat the param for several (cluster[]=a&cluster[]=b) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with group_by (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Amazon ASIN: 10 uppercase letters or digits, e.g. B08GPHNSCW.
"^[A-Z0-9]{10}$""units""glance_views""rank""manufacturing_ordered_sales""manufacturing_ordered_units""manufacturing_shipped_sales""manufacturing_shipped_units""manufacturing_shipped_cogs""manufacturing_net_received_sales""manufacturing_net_received_units""sourcing_shipped_sales""sourcing_shipped_units""sourcing_shipped_cogs""sourcing_net_received_sales""sourcing_net_received_units""sourcing_customer_returns""manufacturing_customer_returns""sourcing_confirmed_units""days_of_coverage"Responses
200
product-brands
Brands present in the authenticated account's catalog. Requires catalog:read. Sparse fieldsets use fields[brand] — keyed by the entity type (brand, the same one expand[]=brand and a product's brand field use), not by the resource name.
List the brands present in the authenticated account's catalog
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Case-insensitive substring match over the brand name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.
1200Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"Responses
200
GET /v1/product-brands/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
List Amazon marketplace countries
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"22Responses
200
GET /v1/countries/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
clusters
The authenticated account's keyword clusters. Requires catalog:read; creating and editing them requires catalog:write.
List the authenticated account's keyword clusters
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Query Parameters
Page size. The default is enough to explore; raise it only when you need to walk a whole collection.
20201100Cursor for the next page: the id of the last record you received. Returns the records after it.
Cursor for the previous page: the id of the first record you received. Returns the records before it.
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Case-insensitive substring match over the cluster name and its positive and negative keywords. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.
1200Set to true to also receive total_count: how many records match every filter of this request, ignoring starting_after/ending_before/offset - the size of the whole result set, not of what is left. has_more is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with group_by), and, with any granularity other than total, each of their periods that has data, not entities times periods: entity-days with granularity=daily. total_count comes back null when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.
"true""false"Responses
200
Create a keyword cluster
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Header Parameters
Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.
1255Request Body
Responses
201
GET /v1/clusters/{id}
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Query Parameters
Inline related records instead of returning just their ids. Repeat the param for several (expand[]=connection&expand[]=country) and nest with dot notation (connection.country), up to 4 levels.
Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: fields[campaign]=id,name. A key that matches no entity is ignored silently and the full object comes back.
Responses
200
Delete a keyword cluster
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Header Parameters
Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.
1255Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Responses
200
Add or remove keywords and products of a cluster, or rename it
Authorizations
Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....
Parameters
Header Parameters
Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.
1255Path Parameters
24-character hexadecimal Mongo ObjectId.
"^[a-f0-9]{24}$"Request Body
Responses
200