---
search:
  tags:
    - Insights
    - GET
seo:
  description: >-
    Available on: Meta TikTok Google Ads Reference for the GET /observe/insights
    endpoint in the AdCrunch API.
sidebar:
  label: 'Stored read: List insights'
  badge: GET
title: 'Stored read: List insights'
type: openapi-operation
---
**Available on:** [![Meta](/providers/meta.svg)](https://docs.adcrunch.dev/connect/providers) [![TikTok](/providers/tiktok.svg)](https://docs.adcrunch.dev/connect/providers) [![Google Ads](/providers/gads.svg)](https://docs.adcrunch.dev/connect/providers)

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.

| `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 `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.

`GET /observe/insights`