Stored read: List insights

Available on:

Gives aggregated metric rows for your organization: what an ad account, a campaign, an ad group or an ad spent over a date range, and what it returned.

Each row carries the metrics you name in select. The default metrics are spend and impressions. Each row also carries a currency.

A metric a provider does not report reads 0, and never null. Google Ads reports no reach, so reach, cpp and frequency read 0 on every Google Ads row. Compare those three inside one provider only.

Date range

A date range is required. Send since, and optionally until, both written YYYY-MM-DD. Or send relative: last_7_days, last_15_days or last_month. A request with neither is refused with 400 invalid_request.

Set interval to day, week or month to get one row for each period, each carrying a date. A week is dated by its Monday, a month by its first day. Omit interval to get one row for the whole range.

Filters and groups

advertiserId, entityId, entityType and provider are filters: they decide which rows are read. breakdown is separate: it decides how the rows are grouped, and which columns name the group.

An entity type is the name its provider uses — campaign, adset at Meta, ad_group at TikTok and Google Ads, ad, and so on.

A breakdown deeper than campaign needs a provider or an entity filter, because the levels below a campaign differ per platform. breakdown=adset with no provider is refused with 400 invalid_request, and its issue names the breakdowns that are available.

Money

Money is in whole units of the row’s currency, with decimals: a spend of 1284.57 is 1,284.57. It is the unit a budget takes on an entity, so a budget and a spend compare directly. The Mutations API and a Campaign Plan take the same unit.

Money comes back in the account currency of the rows it came from, and each row says which in its currency. A group that mixes two account currencies answers currency: null — the money in it was added across currencies and cannot be compared.

Send currency — an ISO 4217 code such as USD — to make them comparable. AdCrunch converts each day at the European Central Bank rate of that day, before adding the rows up, and every row then answers that currency.

Advertisers

Omit advertiserId to read every advertiser of your organization in one call. Send it to read one, and AdCrunch then also makes sure your organization owns it. An advertiserId your organization does not own answers an empty list, not a failure.

Paging

The answer is one page, { data, nextCursor }, of at most limit rows (100 by default, 500 at most). When it holds nextCursor, more rows exist: send it back as cursor, with the same parameters, to get the next page.

The rows are in one order across every provider: the period (with an interval), then the advertiser and the entity of the breakdown, then the provider. So a page never splits one group, and the pages of a portfolio read hold no more than limit rows however many providers you connect.

The rows always come from what AdCrunch holds. A live read belongs to one advertiser, and no provider aggregates an organization.

curl -X GET "https://api.pr-701.adcrunch.dev/observe/insights" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.pr-701.adcrunch.dev/observe/insights", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://api.pr-701.adcrunch.dev/observe/insights",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

{
  "data": [
    {
      "advertiserId": "acc_1203456789012345",
      "currency": "EUR",
      "entityId": "120210000000000",
      "impressions": 184213,
      "provider": "meta",
      "spend": 1284.57,
      "type": "campaign"
    },
    {
      "advertiserId": "acc_4829301756",
      "currency": "EUR",
      "entityId": "20481523697",
      "impressions": 46902,
      "provider": "gads",
      "spend": 612.4,
      "type": "campaign"
    }
  ]
}

{
  "issues": [
    {
      "in": "body",
      "message": "string",
      "path": "string"
    }
  ],
  "error": "invalid_request",
  "message": "string"
}

{
  "error": "unauthorized",
  "message": "string"
}

{
  "error": "forbidden",
  "message": "string"
}