Get daily aggregate ad metrics for an account

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 90-day cache window trigger an on-demand backfill from the platform before returning.

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 90-day cache window trigger an on-demand backfill from the platform before returning.

Parameters

• accountId (query, string) required — Social account ID. Sibling-expanded to its linked posting↔ads pair.

• adAccountId (query, string) — Optional platform-native ad account ID (e.g. Meta act_…, TikTok advertiser ID). Use when the connection wraps multiple platform ad accounts and the chart should show one only. Note: rows ingested before 2026-05-13 don't carry this column; the recur...

• fromDate (query, string) — Inclusive start of metrics range (YYYY-MM-DD). Defaults to 90 days ago.

• toDate (query, string) — Inclusive end of metrics range (YYYY-MM-DD). Defaults to today. Max 730-day range.

• platform (query, string) — Restrict to one platform.

Responses

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

• rows (array)

401

403 — Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.