API reference

Reporting API

What the console shows, over HTTP. A live key with the read scope; 120 requests a minute.

Delivery

GET/api/v1/advertisers/reporting/deliverykey (read)

Request

curl -H "Authorization: Bearer $FREEBUFF_ADS_API_KEY" \
  "https://freebuff.com/api/v1/advertisers/reporting/delivery?from=2026-10-01&to=2026-10-07&groupBy=campaign"

Parameter	Type	Description
`from, to`optional	YYYY-MM-DD	Pacific days, inclusive, ≤ 366 apart, not future. Default last 30.
`groupBy`optional	string	`campaign` (default), `creative`, `placement`, `surface`, `country`.
`campaignId, creativeId, placementId, surface, country`optional	repeatable	Filters, ≤ 100 values each. country cannot mix with creative, placement or surface.
`limit, cursor`optional		1–5000 rows per page (default 1000); pass nextCursor back.
`format`optional	string	`csv` downloads the whole selection (≤ 50,000 rows).

Response

{
  "version": "2026-09-04",
  "range": { "from": "2026-10-01", "to": "2026-10-07", "settledThrough": "2026-10-06", "liveDays": 1 },
  "columns": [ { "id": "clicks", "label": "Clicks", "unit": "count" }, { "id": "spend", "label": "Spend", "unit": "cents" }, … ],
  "rows": [
    { "day": "2026-10-01", "settled": true, "campaignId": "…",
      "impressionsServed": 18230, "clicks": 212, "conversions": 9, "spend": 42400, "ctr": 0.0116, …,
      "trustedRealClicks": 205, "excludedInternalClicks": 3, "excludedInvalidClicks": 4, "unknownTrafficClicks": 0 }
  ],
  "totals": { "impressionsServed": 121904, "clicks": 1388, "spend": 277600, … },
  "nextCursor": null
}

Columns

Column	Meaning
`impressionsServed, impressionsViewed, viewRate`	Delivered, confirmed rendered, and the ratio.
`reach, frequency`	Unique viewers over the range and impressions per viewer.
`clicks, ctr`	Clicks and clicks per served impression.
`conversions, cvr`	Reported conversions and conversions per click.
`spend, ecpc, ecpm, costPerResult`	Cents. A filtered slice reports only its own spend.
`eventCount:<type>, costPerEvent:<type>`	One pair per event type on the account.
`invalidClicksCredited, invalidTrafficCredits`	Clicks credited back as invalid, and the amount.
`trustedReal…, excludedInternal…, excludedInvalid…, unknownTraffic…`	Served, viewed and clicks split four ways; they sum to the total. Null means unknown, not zero.

columns in the response lists every id with a label and a unit (count, cents, ratio). CSV header: day,settled,campaignId, the grouping column, then the column ids.

Conversions

GET/api/v1/advertisers/reporting/conversionskey (read)

Request

curl -H "Authorization: Bearer $FREEBUFF_ADS_API_KEY" \
  "https://freebuff.com/api/v1/advertisers/reporting/conversions?from=2026-10-01&to=2026-10-07&eventType=signup_completed"

Parameter	Type	Description
`from, to`optional	YYYY-MM-DD	Both or neither. Default last 30 days.
`campaignId, eventType`optional	repeatable	Filters, ≤ 100 values each.
`includeTest`optional	boolean	Include Test events. Default false.
`limit, cursor`optional		1–5000 (default 1000); cursors are signed to your account.
`format`optional	string	csv downloads conversion-events.csv.

Response

{
  "version": "2026-09-04",
  "rows": [
    { "eventId": "signup_completed:12345", "campaignId": "…", "campaignName": "Launch — US",
      "eventType": "signup_completed", "occurredAt": "2026-10-03T17:04:11.000Z",
      "settlementStatus": "not_billable", "settlementReason": null, "chargedCents": 0,
      "isTest": false, "reportedVia": "s2s", "matchedVia": "click_id" }
  ],
  "nextCursor": "adrc_1…"
}

Fields

Field	Meaning
`eventId`	Yours, or a derived id for a pixel rule.
`settlementStatus, chargedCents`	not_billable and 0 except on a rate-card campaign.
`reportedVia`	s2s, client (pixel or v1 tag), connector, server.
`matchedVia`	click_id or identity_email.

CSV headers: Event ID, Campaign ID, Campaign, Event type, Occurred at, Settlement status, Settlement reason, Charged cents, Test event, Reported via, Matched via.

Notes

Numbers come from the console's own column catalogue, so they match it for the same selection.
A settled day has its final rollup. Later days are read live and can still move.
≤ 100 campaigns per request, ≤ 50,000 rows processed.
Same data over MCP: get_delivery_report, list_conversions.

Status	Body	Meaning
400	`{ "error": "<sentence>" }`	Bad date, range, cursor, limit or filter mix.
401	`unauthorized`	No read scope, or a test key.
413	`{ "error": "export exceeds 50000 rows…" }`	Narrow the range.
429	`rate_limited`	Retry-After is set.