---
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) — 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.

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

- object
  - `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–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).
    - `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.
  - `backfillPending` boolean — Present and true only on `202` responses: part of the requested date range is still being backfilled from the platform in the background. Retry the same request shortly; it returns 200 once the range is fully ingested.

## Other responses

- `202` — Part of the requested date range predates the ingested history; a background backfill job has been queued. The body has the same shape as the 200 response, carries the currently-available data, and includes `backfillPending: true`. A `Retry-After` header carries the recommended poll interval in seconds. Allow the job a short time to run (typically 1-3 minutes) and submit the request again; once ingestion completes the same request returns 200 with the full range.
- `400` — Invalid request
- `401` — Unauthorized
- `403` — Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/f81ca70ea6b9/schema)