Publisher insights

GET /v1/publisher/insights returns your performance on AI Surfaces, on the web or on UGC for a date range: delivered impressions, clicks and estimated earnings, plus requests and fill on AI Surfaces and UGC, viewed impressions on AI Surfaces and the web, and page views on the web. Rows come by day, by month or as one total, and can be split by country and US state.

Request

GET https://api.adzen.ai/v1/publisher/insights

The path with a trailing slash (/v1/publisher/insights/) also works.

Headers

Which key you use depends on your surface:

• AI Surfaces: the key you use for POST /v1/ai/process.
• Web and UGC: a read-only reporting key. Ask your Adzen account representative for one. It works on this endpoint only. A UGC partner’s /v1/ugc key doesn’t work here, and the reporting key doesn’t work there.

You read only the data of the account that owns the key. An account is on one surface, and meta.surface says which (ai, web or ugc). This endpoint rejects any parameter not listed below with 400 unknown_parameter.

Parameters

• The range is at most 93 days, and end_date can’t be after the current date in timezone.
• Only an omitted parameter takes its default. A parameter sent with an empty value is an error: timezone= returns unsupported_timezone, start_date= or end_date= returns invalid_date, and breakdowns= returns invalid_breakdown.
• Days and months are local to timezone. A day that changes clock time has 23 or 25 hours, and still comes back as one row.
• month rows are clamped to your range: a range from the 13th to the 29th returns one row with those 17 days.
• Without breakdowns, total returns exactly one row, even when every count is zero. With breakdowns, total returns one row per country or region that has activity, and one all-zero row with the breakdown fields set to null when there is no activity.
• breakdowns=region adds both country and region. Values in breakdowns can come in any order, with spaces around the comma.

Example

curl -G https://api.adzen.ai/v1/publisher/insights \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d start_date=2026-10-22 \
  -d end_date=2026-10-24 \
  -d granularity=total

Response

{
  "data": [
    {
      "page_views": null,
      "ad_requests": 6,
      "blocked_requests": 1,
      "eligible_requests": 5,
      "matched_requests": 4,
      "fill_rate": 0.666667,
      "eligible_fill_rate": 0.8,
      "impressions": 6,
      "viewed_impressions": 3,
      "clicks": 2,
      "invalid_impressions": 1,
      "invalid_clicks": 1,
      "ctr": 0.333333,
      "viewed_ctr": 0.666667,
      "estimated_revenue_micros": 1575000,
      "rpm_micros": 262500000,
      "ecpm_micros": 262500000,
      "epc_micros": 787500
    }
  ],
  "meta": {
    "surface": "ai",
    "start_date": "2026-10-22",
    "end_date": "2026-10-24",
    "timezone": "UTC",
    "currency": "USD",
    "data_available_end": "2026-10-30T00:35:01.020458Z",
    "first_incomplete_date": null,
    "warnings": []
  }
}

With granularity=day each row also has date (YYYY-MM-DD); with month, a month (YYYY-MM). With breakdowns=region, each row has country and region:

{
  "date": "2026-10-22",
  "country": "US",
  "region": "US-CA",
  "page_views": null,
  "ad_requests": 1,
  "blocked_requests": 0,
  "eligible_requests": 1,
  "matched_requests": 1,
  "fill_rate": 1.0,
  "eligible_fill_rate": 1.0,
  "impressions": 2,
  "viewed_impressions": 2,
  "clicks": 1,
  "invalid_impressions": 1,
  "invalid_clicks": 0,
  "ctr": 0.5,
  "viewed_ctr": 0.5,
  "estimated_revenue_micros": 875000,
  "rpm_micros": 875000000,
  "ecpm_micros": 437500000,
  "epc_micros": 875000
}

On the web the same row has page_views, and the request funnel is null (web pages don’t send ad requests the way an AI integration does):

{
  "date": "2026-10-18",
  "country": "US",
  "region": "US-CA",
  "page_views": 3,
  "ad_requests": null,
  "blocked_requests": null,
  "eligible_requests": null,
  "matched_requests": null,
  "fill_rate": null,
  "eligible_fill_rate": null,
  "impressions": 1,
  "viewed_impressions": 1,
  "clicks": 1,
  "invalid_impressions": 1,
  "invalid_clicks": 0,
  "ctr": 1.0,
  "viewed_ctr": 1.0,
  "estimated_revenue_micros": 611525,
  "rpm_micros": 203841666,
  "ecpm_micros": 611525000,
  "epc_micros": 611525
}

On UGC the row has the request funnel, no page views, and no viewed impressions (see Viewed impressions). With a location breakdown, requests are in the row with no location, because a request has no viewer:

{
  "date": "2026-10-28",
  "country": "US",
  "region": "US-CA",
  "page_views": null,
  "ad_requests": 0,
  "blocked_requests": 0,
  "eligible_requests": 0,
  "matched_requests": 0,
  "fill_rate": null,
  "eligible_fill_rate": null,
  "impressions": 4,
  "viewed_impressions": null,
  "clicks": 1,
  "invalid_impressions": 1,
  "invalid_clicks": 1,
  "ctr": 0.25,
  "viewed_ctr": null,
  "estimated_revenue_micros": 500000,
  "rpm_micros": null,
  "ecpm_micros": 125000000,
  "epc_micros": 500000
}

Rows

• With day or month, a row comes back only for a period, country and region that has at least one event. A day with no activity has no row. Treat a missing row as zero.
• Rows are sorted by period, oldest first, then by country, then by region. A null country or region sorts first.
• A response is at most 20,000 rows. A request that would return more fails with 400 too_many_rows. Narrow the date range or the breakdowns.

Fields

Every row has every field. A field that doesn’t apply to your surface is null, never 0:

Counts

Rates. Fractions from 0 to 1, rounded to 6 places. A rate is null, not 0, when its denominator is 0.

Earnings. All money is in micros of USD (1 USD = 1,000,000 micros), rounded down.

rpm_micros, ecpm_micros and epc_micros are null when their denominator is 0 or earnings aren’t available.

Location

country (ISO 3166-1, such as US) and region (ISO 3166-2, such as US-CA) are set as follows:

• AI Surfaces: from the location you sent on POST /v1/ai/process. A location that Adzen can’t parse gives country alone, or neither. Blocked requests have no location, so their rows have country and region set to null.
• Web: from the visitor’s connection, as the Adzen edge sees it. region is set for US visitors only. Traffic from before Adzen began recording location, and the rare visitor Adzen can’t place, is in rows with country and region set to null. The location_partial warning says when your window reaches back that far.
• UGC: from the viewer’s connection, as on the web, for impressions, clicks and earnings. Requests have no viewer, so with a breakdown every request is in the rows with country and region set to null. Viewer location is recorded from November 4, 2026. Earlier traffic is in the null rows, and location_partial says so.

On every surface the rows of a breakdown add up to the totals.

Dating rules

• Requests are dated when you sent them (AI Surfaces: the first attempt). Page views (web) are dated when the page was viewed.
• UGC data starts on September 11, 2026. Earlier days return no rows.
• Impressions and clicks are dated when they happened, so a click can land on a later day than its request.
• Earnings are dated by the event that was charged: the click for CPC campaigns, the viewed impression for CPM campaigns.

meta

Finality and estimates

Data refreshes about every 15 minutes. meta.data_available_end gives the point the data covers.

Counts can change for 72 hours after a day ends, as late events arrive and invalid traffic is removed. Pull recent days again until they are past first_incomplete_date.

estimated_revenue_micros is not your payout. Your payout comes from the monthly statement, which can differ after invalid-traffic review and adjustments. Earnings are computed per row and rounded down, so breakdown rows can add up to a little less than the total row (at most 1 micro per row). Counts always add up exactly.

Viewed impressions

• Web: the Adzen tag measures it. An ad counts as viewed once any part of it has been on screen for one continuous second.
• AI Surfaces: viewed_impressions counts the view beacons Adzen receives. See Impression beacons for when a view beacon fires.
• UGC: there is one impression pixel, fired when the post displays the ad. It isn’t a viewability measurement, so viewed_impressions and viewed_ctr are null. Use impressions and ctr.

Errors

Every error has the same shape. param is null when no single parameter caused the error.

{
  "error": {
    "type": "invalid_request_error",
    "code": "range_too_large",
    "message": "the date range is limited to 93 days",
    "param": "end_date"
  }
}

401 responses carry WWW-Authenticate: ApiKey realm="adzen", header="X-API-Key".

Adzen checks a request in this order and returns the first error it finds:

1. The API key (401, 403 account_disabled, 503 authentication_unavailable).
2. Whether reporting is enabled (403 reporting_not_enabled).
3. The rate limit (429).
4. The parameters (400).

Rate limit

60 requests per minute for each publisher account, counted across all keys of that account. The window is the clock minute: the count resets at the start of each minute, not 60 seconds after your first request.

Every request that passes the key and reporting checks counts, including requests that then fail with 400, 429 or 503.

Successful responses and 429s carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the current minute ends). A 429 adds Retry-After with the same value. Wait that many seconds before retrying. See Rate limits for limits across products.

Polling

Poll at most once every 15 minutes. Use breakdowns to get every country and region in one call. When first_incomplete_date is not null, request the days from that date to the current date on each poll and replace your stored counts for those days.