Skip to main content
GET
Get Brand Analytics
Get analytics for a brand — running-ads distribution and creative velocity. A successful call returns one row per day in data[] (date, active_count, inactive_count, and per-format counts). Optionally scope with start_date / end_date and order. ⚠️ The id parameter must be a page_id / ad_library_id, NOT a Foreplay brand_id. Passing a brand_id returns HTTP 406. Get the ad_library_id from get_foreplay-getbrandsbydomain first. Flow: getBrandsByDomain(domain)ad_library_idbrand/analytics(id=ad_library_id). ⚠️ Date window: the range between start_date and end_date must be ≤ 30 days. A larger range returns HTTP 406 Date range too large:
So this endpoint has two 406 cases: (1) a brand_id was passed instead of a page_id / ad_library_id, and (2) the date window exceeds 30 days. Billing: 0.02625peritemreturnedindata[];emptyresultsanderrorsarenotcharged.Becausetheresponseisonerowperday,eachreturnedrowis1billeditem(0.02625 per item returned in `data[]`; empty results and errors are not charged.** Because the response is one row per day, **each returned row is 1 billed item (0.02625) — a 30-day window can bill up to ~30 items, which matters for cost estimation. A 406 (either case) is not charged. Example: resolve a domain first (e.g. getBrandsByDomain?domain=nike.comad_library_id: "15087023444"), then query analytics with that id: GET /foreplay/brand/analytics?id=15087023444&start_date=2025-01-01&end_date=2025-01-30. Related: get_foreplay-getbrandsbydomain, get_foreplay-getadsbybrandid, get_foreplay-discovery-ads.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

id
string
required

Page ID or Brand ID. Brand IDs are 20-25 character alphanumeric strings with mixed case. Page IDs are numeric Facebook page identifiers.

start_date
string

Start date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS', or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g. '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To get all ads from a specific day, set end_date to 'YYYY-MM-DD 23:59:59' or to the next day at '00:00:00'. Examples: start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59. The window between start_date and end_date must be ≤ 30 days. A larger range returns HTTP 406 Date range too large.

end_date
string

End date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS', or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g. '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To include all results for a given day, set end_date to 'YYYY-MM-DD 23:59:59' or to the next day at '00:00:00'. Examples: start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59. The window between start_date and end_date must be ≤ 30 days. A larger range returns HTTP 406 Date range too large.

order
enum<string>
default:newest

Order of results: 'newest' (default), 'oldest', 'longest_running', or 'most_relevant'. Sorts ads by creation date, longest running duration, or relevance to the search query.

Available options:
newest,
oldest,
longest_running,
most_relevant

Response

JSON envelope with metadata and a data[] array of analytics rows (one row per day, each with date, active_count, inactive_count, and per-format counts). Each row in data[] counts as one billed item.

The response is of type object.