List insights

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.

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 a 422.

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.

`breakdown`	Rows	Each row also carries
omitted	one, for everything that matched	nothing else
`provider`	one for each ad platform	`provider`
`advertiser`	one for each ad account	`provider`, `advertiserId`
an entity type	one for each entity of that type	`provider`, `advertiserId`, `entityId`, `type`

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 a 422 that names the breakdowns that are available.

Money

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.

GET/observe/insights

Authorization

AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>. Two credentials work.

An API key (acr_…) is what a server integration uses. Create one in the AdCrunch console under Settings → API keys — see https://docs.adcrunch.dev/account/api-keys. A key is bound to the organization that was active when you created it, and it keeps acting on that organization whatever you do later. It carries the permissions of the member who created it.

A session issued by the AdCrunch sign-in flow also works, which is how the console calls this service from the browser.

Either way the organization comes from the credential. There is no organization parameter.

Query parameters

advertiserIdstring

Filter rows to a single advertiser. Short-circuits the per-org advertiser fan-out and verifies the advertiser belongs to the caller's organization.

matches ^(acc_)[\s\S]{0,}$

breakdownstring

Group results by this level. Use a provider-native entity type (campaign, adset, ad_group, line_item, asset_group, keyword, ad, …) or provider/advertiser. Omit to aggregate every matching row into one result.

Allowed:provideradvertisercampaignadsetadgroupad_groupad_group_adinsertion_orderline_itemasset_groupkeywordaudiencelisting_groupadcreative

currencystring

Display currency (ISO 4217, e.g. USD). When provided, monetary metrics are converted from each row’s account currency using the ECB reference rate of the row’s own date, before any aggregation. Omit to get unconverted account-currency values — pass it whenever the organization has advertisers in more than one currency.

matches ^[A-Za-z]{3}$

entityIdstring

Filter to a single entity (any type), or — combined with an entity-type breakdown — scope the breakdown to that entity’s subtree.

entityTypestring

Filter rows to a single provider-native entity type.

intervalstring

Bucket the time series at this granularity. Omit to collapse to a single row per group.

Allowed:dayweekmonth

limitnumber

Page size. Clamped to 100.

min 1 · max 100

offsetnumber

Pagination offset.

min 0

providerstring

Restrict to a single provider. Ignored when an entity filter (advertiserId, etc.) is provided — that filter already pins the provider.

relativestring

selectstring | string[]

Metric columns to include on each row, as a comma-separated string (e.g. spend,clicks,ctr) or repeated values. Defaults to spend,impressions.

sincestring

untilstring

Responses

200

The matching rows. An empty array means nothing matched.

Array of object

advertiserIdstring

The ad account this row belongs to, prefixed acc_. Present when breakdown is advertiser or an entity type.

currencystring | nullrequired

The ISO 4217 currency the money in this row is expressed in. It is the account currency when every row in the group shares one, the currency you asked for when you sent currency, and null when the group mixes two or more account currencies. A null here means the money in this row was added up across currencies and cannot be compared — send currency to make it comparable.

datestring

The first day of the period, YYYY-MM-DD. Present only when you send interval. A week is dated by its Monday, a month by its first day.

entityIdstring

The entity this row belongs to, as the bare id its provider gives it. Present when breakdown is an entity type.

providerstring

The ad platform: meta, tiktok, gads, snapchat or dv360. Present when breakdown is set to anything.

typestring

The provider entity type of entityId, for example campaign, adset, ad_group or ad. Present when breakdown is an entity type.

spendnumber

Money spent, in the row’s currency.

clicksnumber

Clicks.

impressionsnumber

Impressions.

ctrnumber

Click-through rate, as a percentage: clicks ÷ impressions × 100. A ctr of 1.5 means 1.5%.

cpcnumber

Cost per click: spend ÷ clicks.

cpmnumber

Cost per thousand impressions: spend ÷ impressions × 1000.

cppnumber

Cost per thousand people reached: spend ÷ reach × 1000. Google Ads reports no reach, so this reads 0 there.

cpanumber

Cost per conversion: spend ÷ conversions.

roasnumber

Return on ad spend: conversion value ÷ spend.

reachnumber

People reached. Google Ads does not report it, so it reads 0 there.

frequencynumber

Impressions ÷ reach. Google Ads reports no reach, so this reads 0 there.

conversionsnumber

Conversions, as the provider counts them.

conversion_valuenumber

The value attributed to those conversions, as money.

action_add_to_cartnumber

Add-to-cart actions. Meta only; other providers read 0.

action_add_to_cart_valuenumber

The value attributed to those add-to-cart actions. Meta only.

action_purchasenumber

Purchases. Meta only; other providers read 0.

action_purchase_valuenumber

The value attributed to those purchases. Meta only.

action_initiate_checkoutnumber

Checkouts started. Meta only; other providers read 0.

action_initiate_checkout_valuenumber

The value attributed to those checkouts. Meta only.

401

No credential, or one that does not resolve. Send an API key or a session. See the security scheme. error is unauthorized.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:unauthorized

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

403

The caller does not hold observe:read. error is forbidden.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:forbidden

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

422

The request did not match this operation’s schema. This is the framework’s own shape, not the error/message one.

errorsobject[]required

One entry per failing field.

foundanyrequired

What was sent.

messagestringrequired

onstringrequired

Which part of the request failed: body, query or params.

propertystringrequired

The field that failed.

typestringrequired

Allowed:validation

Request

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

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

import requests

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

Response

[
  {
    "advertiserId": "string",
    "currency": "string",
    "date": "string",
    "entityId": "string",
    "provider": "string",
    "type": "string",
    "spend": 0,
    "clicks": 0,
    "impressions": 0,
    "ctr": 0,
    "cpc": 0,
    "cpm": 0,
    "cpp": 0,
    "cpa": 0,
    "roas": 0,
    "reach": 0,
    "frequency": 0,
    "conversions": 0,
    "conversion_value": 0,
    "action_add_to_cart": 0,
    "action_add_to_cart_value": 0,
    "action_purchase": 0,
    "action_purchase_value": 0,
    "action_initiate_checkout": 0,
    "action_initiate_checkout_value": 0
  }
]

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

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

{
  "errors": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "found": null,
  "message": "string",
  "on": "string",
  "property": "string",
  "type": "validation"
}