Skip to content

Advertising

The campaign tree and its performance. Requires campaigns:read.

Each level pairs a structure resource with a metrics one: /v1/campaigns lists what exists, /v1/campaign-metrics lists what it did over a date range.

Servers

https://api.epinium.com

campaigns

The authenticated account's advertising campaigns. Requires campaigns:read.


List the authenticated account's advertising campaigns

GET
/v1/campaigns

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

limit

Page size. The default is enough to explore; raise it only when you need to walk a whole collection.

Type
integer
Example20
Default
20
Minimum
1
Maximum
100
starting_after

Cursor for the next page: the id of the last record you received. Returns the records after it.

Type
string
ending_before

Cursor for the previous page: the id of the first record you received. Returns the records before it.

Type
string
expand

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.

fields

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.

Type
object
search

Case-insensitive substring match over the campaign 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.

Type
string
Min Length
1
Max Length
200
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
state
Type
string
Valid values
"ENABLED""PAUSED""ARCHIVED""OTHER"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"adProduct": "string",
  
  
  
"campaignId": "string",
  
  
  
"name": "string",
  
  
  
"state": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"startDate": "string",
  
  
  
"endDate": "string",
  
  
  
"deliveryStatus": "string",
  
  
  
"deliveryReasons": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"budget": {
  
  
  
  
"amount": 0,
  
  
  
  
"currency": "string",
  
  
  
  
"period": "string"
  
  
  
},
  
  
  
"bidStrategy": "string",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


GET /v1/campaigns/{id}

GET
/v1/campaigns/{id}

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

expand

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.

fields

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.

Type
object

Responses

200

application/json
JSON
{
  
"id": "string",
  
"adProduct": "string",
  
"campaignId": "string",
  
"name": "string",
  
"state": "string",
  
"connection": "string",
  
"country": "string",
  
"startDate": "string",
  
"endDate": "string",
  
"deliveryStatus": "string",
  
"deliveryReasons": [
  
  
"string"
  
],
  
"budget": {
  
  
"amount": 0,
  
  
"currency": "string",
  
  
"period": "string"
  
},
  
"bidStrategy": "string",
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground

Authorization
Variables
Key
Value

Samples


Changes the workflow actually applied to this campaign

GET
/v1/campaigns/{id}/optimization-history

Only changes that were APPLIED, and only for real: a dry-run simulation never appears here, under any parameter. Aggregated to a net per entity — data carries one row per target whose bid was moved, with the bid from before the first change against the bid after the last one, so a target raised then capped back down reports direction: unchanged with change_count: 2. That is the reading a flat decision list hides, and it is usually the answer to whether the optimization is doing anything. Proposals are excluded: the optimizer computes a bid the economic ceiling can then cut, and only what reached Amazon is reported. Non-bid changes (harvested keywords, negatives, placement adjustments, blocked or quarantined targets) do not share the table because they have no previous bid — they are counted in other_changes. Monetary amounts are decimal strings. The window is capped at 90 days, which is the retention of the underlying records.

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

start_date
Type
string
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
end_date
Type
string
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
limit

Page size, up to 500. Paginate with offset, not with a cursor: these rows are aggregated changes, not records with an id. Narrow the window with start_date / end_date instead of walking every page.

Type
integer
Default
100
Minimum
1
Maximum
500
offset
Type
integer
Default
0
Minimum
0
Maximum
9007199254740991
order
Type
string
Valid values
"asc""desc"
Default
"desc"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"entity_type": "string",
  
  
  
"adgroup": "string",
  
  
  
"first_bid": "string",
  
  
  
"last_bid": "string",
  
  
  
"net_change": "string",
  
  
  
"direction": "string",
  
  
  
"change_count": 0,
  
  
  
"first_change_at": "string",
  
  
  
"last_change_at": "string",
  
  
  
"last_reason": "string",
  
  
  
"last_scenario": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0,
  
"other_changes": [
  
  
{
  
  
  
"entity_type": "string",
  
  
  
"entity_id": "string",
  
  
  
"change_type": "string",
  
  
  
"count": 0,
  
  
  
"last_change_at": "string",
  
  
  
"last_reason": "string"
  
  
}
  
],
  
"summary": {
  
  
"targets_touched": 0,
  
  
"bid_changes": 0,
  
  
"raised": 0,
  
  
"lowered": 0,
  
  
"unchanged": 0,
  
  
"other_changes": 0,
  
  
"window": {
  
  
  
"start_date": "string",
  
  
  
"end_date": "string"
  
  
}
  
}
}

Playground

Authorization
Variables
Key
Value

Samples


campaign-metrics

Advertising performance per campaign, aggregated from the account's report history. Requires campaigns:read.


Advertising performance per campaign, from the account's report history

GET
/v1/campaign-metrics

Aggregated from the report history over a required start_date/end_date window. 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; ratios are fractions (0.1642 = 16.42%) and are null, never 0, when their denominator is zero.

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

start_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-01"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
end_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-31"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
granularity
Type
string
Valid values
"total""daily"
Example"total"
Default
"total"
limit

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.

Type
integer
Example100
Default
100
Minimum
1
Maximum
1000
offset
Type
integer
Example0
Default
0
Minimum
0
Maximum
9007199254740991
order
Type
string
Valid values
"asc""desc"
Example"desc"
Default
"desc"
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_product
Type
string
Valid values
"SP""SB""SD"
order_by
Type
string
Valid values
"cost""sales""impressions""clicks""orders""units""acos""roas""ctr""cpc""conversion_rate"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"campaign": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"ad_product": "string",
  
  
  
"currency": "string",
  
  
  
"date": "string",
  
  
  
"impressions": 0,
  
  
  
"clicks": 0,
  
  
  
"cost": "string",
  
  
  
"sales": "string",
  
  
  
"orders": 0,
  
  
  
"units": 0,
  
  
  
"ctr": 0,
  
  
  
"cpc": "string",
  
  
  
"acos": 0,
  
  
  
"roas": 0,
  
  
  
"conversion_rate": 0,
  
  
  
"top_of_search_is": 0,
  
  
  
"new_to_brand_sales": "string",
  
  
  
"new_to_brand_purchases": 0,
  
  
  
"detail_page_views": 0,
  
  
  
"viewable_impressions": 0
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


adgroups

The authenticated account's ad groups. Requires campaigns:read.


List the authenticated account's ad groups

GET
/v1/adgroups

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

limit

Page size. The default is enough to explore; raise it only when you need to walk a whole collection.

Type
integer
Example20
Default
20
Minimum
1
Maximum
100
starting_after

Cursor for the next page: the id of the last record you received. Returns the records after it.

Type
string
ending_before

Cursor for the previous page: the id of the first record you received. Returns the records before it.

Type
string
expand

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.

fields

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.

Type
object
search

Case-insensitive substring match over the ad group 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.

Type
string
Min Length
1
Max Length
200
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
state
Type
string
Valid values
"ENABLED""PAUSED""ARCHIVED""OTHER"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"adProduct": "string",
  
  
  
"adGroupId": "string",
  
  
  
"name": "string",
  
  
  
"state": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"campaign": "string",
  
  
  
"adGroupTargetType": "string",
  
  
  
"deliveryStatus": "string",
  
  
  
"deliveryReasons": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


GET /v1/adgroups/{id}

GET
/v1/adgroups/{id}

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

expand

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.

fields

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.

Type
object

Responses

200

application/json
JSON
{
  
"id": "string",
  
"adProduct": "string",
  
"adGroupId": "string",
  
"name": "string",
  
"state": "string",
  
"connection": "string",
  
"country": "string",
  
"campaign": "string",
  
"adGroupTargetType": "string",
  
"deliveryStatus": "string",
  
"deliveryReasons": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground

Authorization
Variables
Key
Value

Samples


adgroup-metrics

Performance per ad group over a date range.


Advertising performance per ad group, from the account's report history

GET
/v1/adgroup-metrics

Aggregated from the report history over a required start_date/end_date window. Like the rest of the metrics resources it 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; ratios are fractions (0.1642 = 16.42%) and are null, never 0, when their denominator is zero.

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

start_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-01"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
end_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-31"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
granularity
Type
string
Valid values
"total""daily"
Example"total"
Default
"total"
limit

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.

Type
integer
Example100
Default
100
Minimum
1
Maximum
1000
offset
Type
integer
Example0
Default
0
Minimum
0
Maximum
9007199254740991
order
Type
string
Valid values
"asc""desc"
Example"desc"
Default
"desc"
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_group

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_product
Type
string
Valid values
"SP""SB""SD"
order_by
Type
string
Valid values
"cost""sales""impressions""clicks""orders""units""acos""roas""ctr""cpc""conversion_rate"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"ad_group": "string",
  
  
  
"campaign": "string",
  
  
  
"ad_product": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"currency": "string",
  
  
  
"date": "string",
  
  
  
"impressions": 0,
  
  
  
"clicks": 0,
  
  
  
"cost": "string",
  
  
  
"sales": "string",
  
  
  
"orders": 0,
  
  
  
"units": 0,
  
  
  
"ctr": 0,
  
  
  
"cpc": "string",
  
  
  
"acos": 0,
  
  
  
"roas": 0,
  
  
  
"conversion_rate": 0,
  
  
  
"new_to_brand_sales": "string",
  
  
  
"new_to_brand_purchases": 0,
  
  
  
"detail_page_views": 0,
  
  
  
"viewable_impressions": 0
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


targets

The authenticated account's advertising targets. Requires campaigns:read.


List the authenticated account's advertising targets

GET
/v1/targets

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

limit

Page size. The default is enough to explore; raise it only when you need to walk a whole collection.

Type
integer
Example20
Default
20
Minimum
1
Maximum
100
starting_after

Cursor for the next page: the id of the last record you received. Returns the records after it.

Type
string
ending_before

Cursor for the previous page: the id of the first record you received. Returns the records before it.

Type
string
expand

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.

fields

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.

Type
object
search

Case-insensitive substring match over the target's expression (keyword, ASIN or category, chosen by targetType) and its matchType; with targetType set, only that type's field is searched. 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.

Type
string
Min Length
1
Max Length
200
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
adGroup

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
state
Type
string
Valid values
"ENABLED""PAUSED""ARCHIVED""OTHER"
targetType
Type
string
Valid values
"AUTO""KEYWORD""PRODUCT_CATEGORY""PRODUCT""PRODUCT_CATEGORY_AUDIENCE""PRODUCT_AUDIENCE""AUDIENCE""THEME"
negative
Type
string
Valid values
"true""false"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"adProduct": "string",
  
  
  
"targetId": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"campaign": "string",
  
  
  
"adGroup": "string",
  
  
  
"state": "string",
  
  
  
"negative": true,
  
  
  
"bid": 0,
  
  
  
"targetType": "string",
  
  
  
"targetLevel": "string",
  
  
  
"deliveryStatus": "string",
  
  
  
"deliveryReasons": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


GET /v1/targets/{id}

GET
/v1/targets/{id}

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

expand

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.

fields

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.

Type
object

Responses

200

application/json
JSON
{
  
"id": "string",
  
"adProduct": "string",
  
"targetId": "string",
  
"connection": "string",
  
"country": "string",
  
"campaign": "string",
  
"adGroup": "string",
  
"state": "string",
  
"negative": true,
  
"bid": 0,
  
"targetType": "string",
  
"targetLevel": "string",
  
"deliveryStatus": "string",
  
"deliveryReasons": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground

Authorization
Variables
Key
Value

Samples


target-metrics

Performance per target, with its keyword and match type.


Advertising performance per target, from the account's report history

GET
/v1/target-metrics

Aggregated from the report history over a required start_date/end_date window, with the target type and keyword resolved from the catalog. This is one of the two heaviest resources, so its window is capped shorter: 93 days for granularity=total and 31 for daily. Paginates with limit/offset and has_more tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are null, never 0, when their denominator is zero.

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

start_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-01"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
end_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-31"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
granularity
Type
string
Valid values
"total""daily"
Example"total"
Default
"total"
limit

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.

Type
integer
Example100
Default
100
Minimum
1
Maximum
1000
offset
Type
integer
Example0
Default
0
Minimum
0
Maximum
9007199254740991
order
Type
string
Valid values
"asc""desc"
Example"desc"
Default
"desc"
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_group

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
target

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_product
Type
string
Valid values
"SP""SB""SD"
order_by
Type
string
Valid values
"cost""sales""impressions""clicks""orders""units""acos""roas""ctr""cpc""conversion_rate"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"target": "string",
  
  
  
"target_type": "string",
  
  
  
"match_type": "string",
  
  
  
"target_expression": "string",
  
  
  
"campaign": "string",
  
  
  
"ad_group": "string",
  
  
  
"ad_product": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"currency": "string",
  
  
  
"date": "string",
  
  
  
"impressions": 0,
  
  
  
"clicks": 0,
  
  
  
"cost": "string",
  
  
  
"sales": "string",
  
  
  
"orders": 0,
  
  
  
"units": 0,
  
  
  
"ctr": 0,
  
  
  
"cpc": "string",
  
  
  
"acos": 0,
  
  
  
"roas": 0,
  
  
  
"conversion_rate": 0,
  
  
  
"new_to_brand_sales": "string",
  
  
  
"new_to_brand_purchases": 0,
  
  
  
"detail_page_views": 0,
  
  
  
"viewable_impressions": 0
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


product-ads

The authenticated account's advertising product ads. Requires campaigns:read.


List the authenticated account's advertising product ads

GET
/v1/product-ads

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

limit

Page size. The default is enough to explore; raise it only when you need to walk a whole collection.

Type
integer
Example20
Default
20
Minimum
1
Maximum
100
starting_after

Cursor for the next page: the id of the last record you received. Returns the records after it.

Type
string
ending_before

Cursor for the previous page: the id of the first record you received. Returns the records before it.

Type
string
expand

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.

fields

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.

Type
object
search

Case-insensitive substring match over the advertised 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.

Type
string
Min Length
1
Max Length
200
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
adGroup

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
product

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
asin
Type
string
state
Type
string
Valid values
"ENABLED""PAUSED""ARCHIVED""OTHER"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"adProduct": "string",
  
  
  
"adId": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"campaign": "string",
  
  
  
"adGroup": "string",
  
  
  
"product": "string",
  
  
  
"asin": "string",
  
  
  
"sku": "string",
  
  
  
"state": "string",
  
  
  
"adType": "string",
  
  
  
"deliveryStatus": "string",
  
  
  
"deliveryReasons": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


GET /v1/product-ads/{id}

GET
/v1/product-ads/{id}

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

expand

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.

fields

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.

Type
object

Responses

200

application/json
JSON
{
  
"id": "string",
  
"adProduct": "string",
  
"adId": "string",
  
"connection": "string",
  
"country": "string",
  
"campaign": "string",
  
"adGroup": "string",
  
"product": "string",
  
"asin": "string",
  
"sku": "string",
  
"state": "string",
  
"adType": "string",
  
"deliveryStatus": "string",
  
"deliveryReasons": [
  
  
"string"
  
],
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground

Authorization
Variables
Key
Value

Samples


product-ad-metrics

Performance per advertised product, with its ASIN.


Advertising performance per product ad, from the account's report history

GET
/v1/product-ad-metrics

Aggregated from the report history over a required start_date/end_date window. Only Sponsored Products and Sponsored Display have product ads; Sponsored Brands does not, so ad_product accepts SP and SD only. Paginates with limit/offset and has_more tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are null, never 0, when their denominator is zero.

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

start_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-01"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
end_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-31"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
granularity
Type
string
Valid values
"total""daily"
Example"total"
Default
"total"
limit

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.

Type
integer
Example100
Default
100
Minimum
1
Maximum
1000
offset
Type
integer
Example0
Default
0
Minimum
0
Maximum
9007199254740991
order
Type
string
Valid values
"asc""desc"
Example"desc"
Default
"desc"
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_group

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
product_ad

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
asin
Type
string
ad_product
Type
string
Valid values
"SP""SD"
order_by
Type
string
Valid values
"cost""sales""impressions""clicks""orders""units""acos""roas""ctr""cpc""conversion_rate"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"product_ad": "string",
  
  
  
"product": "string",
  
  
  
"asin": "string",
  
  
  
"campaign": "string",
  
  
  
"ad_group": "string",
  
  
  
"ad_product": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"currency": "string",
  
  
  
"date": "string",
  
  
  
"impressions": 0,
  
  
  
"clicks": 0,
  
  
  
"cost": "string",
  
  
  
"sales": "string",
  
  
  
"orders": 0,
  
  
  
"units": 0,
  
  
  
"ctr": 0,
  
  
  
"cpc": "string",
  
  
  
"acos": 0,
  
  
  
"roas": 0,
  
  
  
"conversion_rate": 0,
  
  
  
"new_to_brand_sales": "string",
  
  
  
"new_to_brand_purchases": 0,
  
  
  
"detail_page_views": 0,
  
  
  
"viewable_impressions": 0
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


search-terms

The authenticated account's advertising search terms. Requires campaigns:read.


List the authenticated account's advertising search terms

GET
/v1/search-terms

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

limit

Page size. The default is enough to explore; raise it only when you need to walk a whole collection.

Type
integer
Example20
Default
20
Minimum
1
Maximum
100
starting_after

Cursor for the next page: the id of the last record you received. Returns the records after it.

Type
string
ending_before

Cursor for the previous page: the id of the first record you received. Returns the records before it.

Type
string
expand

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.

fields

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.

Type
object
search

Case-insensitive substring match over the shopper search term text. 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.

Type
string
Min Length
1
Max Length
200
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
adGroup

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
searchTerm
Type
string

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"id": "string",
  
  
  
"adProduct": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"campaign": "string",
  
  
  
"adGroup": "string",
  
  
  
"searchTerm": "string",
  
  
  
"searchTermTargetType": "string",
  
  
  
"targetSourceMatchType": "string",
  
  
  
"lastReportDate": "string",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


GET /v1/search-terms/{id}

GET
/v1/search-terms/{id}

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Path Parameters

id*

24-character hexadecimal Mongo ObjectId.

Type
string
Required
Pattern
"^[a-f0-9]{24}$"

Query Parameters

expand

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.

fields

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.

Type
object

Responses

200

application/json
JSON
{
  
"id": "string",
  
"adProduct": "string",
  
"connection": "string",
  
"country": "string",
  
"campaign": "string",
  
"adGroup": "string",
  
"searchTerm": "string",
  
"searchTermTargetType": "string",
  
"targetSourceMatchType": "string",
  
"lastReportDate": "string",
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground

Authorization
Variables
Key
Value

Samples


search-term-metrics

Performance per shopper query, with its text and matching target.


Advertising performance per shopper search term, from the account's report history

GET
/v1/search-term-metrics

Aggregated from the report history over a required start_date/end_date window, with the shopper query resolved from the catalog into query. Answers "which searches do I spend most on?" — use order_by=cost with limit instead of paging. This is the heaviest resource in the API, so its window is capped shorter: 93 days for granularity=total and 31 for daily. Rows are grouped per search term AND target, because the same text can be matched by different targets. Only Sponsored Products and Sponsored Brands produce search terms, so ad_product accepts SP and SB only. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are null, never 0, when their denominator is zero.

Authorizations

bearer

Client API key (POST /api-keys). Send as Authorization: Bearer epk_live_....

Type
HTTP (bearer)

Parameters

Query Parameters

start_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-01"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
end_date*

Both ends are included in the range. The window is capped, and the cap depends on the resource AND on granularitydaily 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.

Type
string
Required
Example"2026-07-31"
Pattern
"^\\d{4}-\\d{2}-\\d{2}$"
granularity
Type
string
Valid values
"total""daily"
Example"total"
Default
"total"
limit

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.

Type
integer
Example100
Default
100
Minimum
1
Maximum
1000
offset
Type
integer
Example0
Default
0
Minimum
0
Maximum
9007199254740991
order
Type
string
Valid values
"asc""desc"
Example"desc"
Default
"desc"
include_total

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 with granularity=daily it counts entity-days, not entities. 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.

Type
string
Valid values
"true""false"
connection

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
country

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
campaign

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_group

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
target

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
search_term

24-character hexadecimal Mongo ObjectId.

Type
string
Pattern
"^[a-f0-9]{24}$"
ad_product
Type
string
Valid values
"SP""SB"
order_by
Type
string
Valid values
"cost""sales""impressions""clicks""orders""units""acos""roas""ctr""cpc""conversion_rate"

Responses

200

application/json
JSON
{
  
"object": "string",
  
"data": [
  
  
{
  
  
  
"object": "string",
  
  
  
"search_term": "string",
  
  
  
"query": "string",
  
  
  
"target": "string",
  
  
  
"campaign": "string",
  
  
  
"ad_group": "string",
  
  
  
"ad_product": "string",
  
  
  
"connection": "string",
  
  
  
"country": "string",
  
  
  
"currency": "string",
  
  
  
"date": "string",
  
  
  
"impressions": 0,
  
  
  
"clicks": 0,
  
  
  
"cost": "string",
  
  
  
"sales": "string",
  
  
  
"orders": 0,
  
  
  
"units": 0,
  
  
  
"ctr": 0,
  
  
  
"cpc": "string",
  
  
  
"acos": 0,
  
  
  
"roas": 0,
  
  
  
"conversion_rate": 0
  
  
}
  
],
  
"has_more": true,
  
"total_count": 0
}

Playground

Authorization
Variables
Key
Value

Samples


Powered by VitePress OpenAPI

Epinium Documentation