Report Endpoint

GET /v1/report is the single endpoint. Pick a date range + metrics, optionally break down by dimensions. Every row is { dimensions, metrics }.

Parameters

Parameter	Required	Description
`from`	✓	Start (inclusive), ISO 8601
`to`	✓	End (inclusive), ISO 8601. Range max 90 days
`metrics`	✓	Comma-separated metric list
`dimensions`	—	Comma-separated breakdown. Omit for a single total row
`granularity`	—	`hourly` · `daily` · `weekly` · `monthly` — only with the `date` dimension
`campaign_id`	—	Restrict to a single owned campaign
`ad_id`	—	Restrict to a single owned ad
`page`	—	Page number (1-based)
`limit`	—	Rows per page (capped server-side)

Metrics

Metric	Description
`views`	Impressions
`spending`	Spend
`clicks`	Clicks (valid / bot-filtered)
`conversions`	Conversions

Dimensions

Dimension	Description
`date`	Time bucket — hourly/daily/weekly/monthly via `granularity`
`campaign`	Campaign breakdown (`campaign_id` + `name`)
`ad`	Ad breakdown (`ad_id` + `name`)
`keyword`	Keyword breakdown (`name`)

Rules:

No dimensions → a single grand-total row.
One entity dimension (campaign | ad | keyword) may be combined with date — except keyword (totals only).
keyword supports only views, spending, clicks (no conversions).
date is a unix epoch second (UTC, bucket start).

Examples

Campaign × day breakdown

curl -s 'https://reporting.magfiads.com/v1/report?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z&metrics=views,spending,clicks&dimensions=campaign,date&granularity=daily' \
  -H 'Authorization: Bearer <API_KEY>'

{
  "meta": {
    "granularity": "daily",
    "dimensions": ["campaign", "date"],
    "metrics": ["views", "spending", "clicks"],
    "total": 240,
    "page": 1,
    "limit": 500,
    "has_more": false
  },
  "data": [
    {
      "dimensions": { "date": 1780617600, "campaign_id": 10, "name": "Summer Launch" },
      "metrics": { "views": 52100, "spending": 3421.1, "clicks": 88 }
    }
  ]
}

Keyword totals

curl -s 'https://reporting.magfiads.com/v1/report?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z&metrics=views,clicks&dimensions=keyword' \
  -H 'Authorization: Bearer <API_KEY>'

{
  "meta": { "granularity": null, "dimensions": ["keyword"], "metrics": ["views", "clicks"], "total": 12, "page": 1, "limit": 500, "has_more": false },
  "data": [
    { "dimensions": { "name": "Spor" }, "metrics": { "views": 88010, "clicks": 1203 } }
  ]
}

Pagination

meta.total is the total row count. If meta.has_more is true, increment page to fetch the next page:

...&page=2&limit=500

Date conversion

date is a unix epoch second (UTC). Example:

new Date(1780617600 * 1000).toISOString(); // "2026-06-01T00:00:00.000Z"

Full schema → API reference.

On this page