---
title: "Get daily account metrics"
method: GET
path: "/v1/ads/timeline"
tags: ["Ad Campaigns"]
---

# Get daily account metrics

`GET /v1/ads/timeline`

Returns daily aggregate metrics across all ads in a SocialAccount as a single
time series, one row per calendar day in the requested range. Use this for
dashboards that draw a daily-spend or daily-conversions chart, instead of
calling `/v1/ads/tree` once per day.

`accountId` is required. The lookup is sibling-expanded so passing the `metaads`
ID also includes ads under the linked `facebook` / `instagram` posting account
(and vice-versa), the same convention as `/v1/ads/tree` and `/v1/ads`.

Date range defaults to the last 90 days. Capped at 730 days. Ranges older
than the ingested history return a `202` immediately with the covered part
and `backfillPending: true` while the rest is backfilled in the background;
repeat the request shortly until it returns 200 with full data.

With adAccountId set to a Google customer id this is the customer-level performance report (clicks, cost, impressions, conversions, all conversions per day).

## Query parameters

- `accountId` string, required
- `adAccountId` string
- `fromDate` string, date
- `toDate` string, date
- `platform` 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter' | 'openai'

## Response `200`

Daily time series of aggregate metrics. Empty `rows` means the account has no ad activity in the range.

- AdsTimelineResponse
  - `backfillPending` boolean — Present and true while historical data is being backfilled.
  - `rows` object[]
    - `date` string, date
    - `spend` number — Native currency units (matches /ads/tree convention).
    - `impressions` integer
    - `reach` integer — Reach summed across the account's ads for this single day. A person seen by two ads the same day counts twice, and reach is de-duplicated per day only: do NOT sum it across days (people reached on multiple days would be double-counted).
    - `clicks` integer
    - `engagement` integer
    - `ctr` number — Click-through rate as a percentage (0 to 100).
    - `cpc` number — Cost per click in native currency.
    - `cpm` number — Cost per 1000 impressions in native currency.
    - `conversions` number — Sum of conversion events over the range. Fractional values are normal (attribution splitting + Google modeled conversions). Meta: events matching the campaign optimization goal. Google: tracked conversions. X / LinkedIn: reported website/lead conversions (added 2026-07).
    - `allConversions` number — All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept.
    - `costPerConversion` number
    - `actions` object — Per-action-type counts merged across all ads on this day. Keys are platform-native action types.
    - `actionValues` object — Monetary mirror of `actions` in native currency.
    - `purchaseValue` number — Sum of purchase-type action values on this day, native currency.
    - `roas` number — Derived purchaseValue / spend.

## Other responses

- `202` — Historical data is incomplete and backfill remains pending.
- `400` — Invalid request
- `401` — Unauthorized
- `403` — Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

## Changes

- **2026-09-25** `2c04683ce694` — 4 info
  - added the optional property `details/adAccountId` to the response with the `400` status
  - added the optional property `details/createdObjects` to the response with the `400` status
  - added the optional property `details/stage` to the response with the `400` status
  - added the optional property `details/unconfirmedWrite` to the response with the `400` status
- **2026-09-16** `3e6ddf2a99ea` — 1 info
  - added the optional property `details/budgetScope` to the response with the `400` status
- **2026-09-15** `0dba7d004d75` — 2 info
  - added the optional property `details/quotaExhausted` to the response with the `400` status
  - added the optional property `details/quotaScope` to the response with the `400` status
- **2026-09-08** `d7a8fa118ef0` — 2 info
  - added the optional property `allOf[#/components/schemas/AdsTimelineResponse]/rows/items/allConversions` to the response with the `202` status
  - added the optional property `rows/items/allConversions` to the response with the `200` status
- **2026-08-21** `15e893e69e8c` — 1 breaking
  - the `backfillPending` response property const value `true` was removed for the status `202`

[Full history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/timeline/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/b2325332041a?raw)