Export reports to CSV

/reports page → choose level (campaigns / ad sets / ads), date range, columns → click Export → CSV download. Backed by GET /api/v1/reports endpoint (verified). Async for large date ranges (worker fires email when ready). UTF-8 encoded. Use cases: external BI, accounting reconciliation, client deliverables.

Who is this for

Mediabuyers exporting data for external analysis. Finance teams reconciling spend. Anyone who needs ads data in their own BI tool / spreadsheet / external report.

How to export

Step 1: Open Reports

Sidebar → Reports OR /reports. The page shows the report builder.

Step 2: Pick level

Three levels available:

• Campaigns: campaign-level rollup

• Ad sets: per-ad-set detail

• Ads: per-ad granularity

Choose based on the depth your analysis needs.

Step 3: Pick date range

Same range options as Ads Manager:

• Today, Yesterday, Last 7 days, Last 30 days, This month, Last month, Custom

Custom range for arbitrary windows.

Step 4: Pick filters (optional)

Same filter options as Ads Manager: ad account, platform, status, metric thresholds.

Step 5: Pick columns

Default columns: standard metrics (spend, impressions, clicks, CTR, conversions, ROAS, CPA).

Customize:

• Show/hide: tick / untick columns

• Add custom columns: derived metrics if available

• Order: drag to reorder (export respects order)

Step 6: Click Export → CSV

Top-right toolbar → Export → CSV.

For small reports (< 10K rows + < 30 days): instant download.

For large reports (large date range or many rows): async generation:

• Job queued

• Worker processes (1-10 min depending on size)

• Email arrives when ready with download link

• Or check Reports page → Download history

Step 7: Open the CSV

UTF-8 encoded. Headers: include all selected columns + dimensions.

Open in Excel, Google Sheets, BI tool, Python pandas, etc.

Endpoint

GET /api/v1/reports (verified apps/backend/src/routes/api/reports.route.ts).

Query params:

• level: campaign / adset / ad

• start_date, end_date

• account_ids[]: filter by account

• platform: optional platform filter

• metrics[]: which metrics to include

• dimensions[]: groupings (e.g. by day, by ad)

Returns: JSON with rows + metadata. CSV is generated server-side via this data.

File format

Standard CSV:

• UTF-8 encoding

• Comma-separated

• Quoted strings for fields containing commas

• Header row first

• One row per entity per date (or aggregated)

Example header:

date,campaign_name,campaign_id,platform,spend,impressions,clicks,ctr,conversions,roas,cpa

Aggregation level

• Per-day: one row per entity per day (long format; good for time series)

• Aggregated: one row per entity (totals over date range)

Choose per use case:

• BI tools: per-day for time-series visualization

• Client reports: aggregated for top-line summary

• Reconciliation: aggregated for spend totals

Per-platform vs cross-platform

Custom dimensions

Beyond standard metrics, some reports support:

• By placement (Meta Stories vs Feed vs Reels breakdown)

• By device (mobile / desktop / tablet)

• By geo (per-country)

• By age range / gender (demographic breakdown)

Available per platform (Meta has richest, others variable).

Async export workflow

For large exports:

1. Click Export → CSV

2. UI shows "Generating report — we'll email when ready"

3. SQS worker generates the CSV (often 1-10 min for very large exports)

4. Email sent with download link (valid 7 days)

5. Click link → CSV downloads

Email recipients: defaults to your billing email; can configure team-wide notification settings.

Limits

• Max date range: typically 12 months (longer requires manual support)

• Max rows per export: 1M typical; larger may need chunking

• Export frequency: rate-limited (e.g. 10/day per user) to prevent abuse

• File size: typically < 100 MB; very large reports compressed or chunked

Performance considerations

• Small (< 10K rows): instant

• Medium (10-100K rows): 30 sec - 2 min sync

• Large (100K+ rows): async (1-10 min)

• Very large (1M+ rows): may chunk into multiple files

Best practices

Save report templates

For recurring exports: save the config as a report template.

Match date range to use case

• Quick check: Last 7 days

• Monthly client report: Last month + Compare to previous

• Annual review: full year aggregated

Pick the right level

• Strategic review: campaign-level aggregates

• Tactical optimization: ad set-level

• Creative testing: ad-level

Export consistent dimensions

When comparing across periods: export with same dimensions every time. Otherwise comparisons break.

RBAC + audit

Mediabuyer+ to export. Audit log: action: report_export, metadata with level + date range + filters.

What you'll see

After Export CSV:

• For small: download starts immediately

• For large: toast "Report queued — we'll email when ready" + entry in Reports → Pending downloads

• Once ready: download link valid 7 days

Common issues

• "Export hung > 30 min": very large dataset. Split into smaller date ranges + concatenate.

• "CSV missing some campaigns I see in Ads Manager": filter mismatch. Check report filters match what's in Ads Manager.

• "CSV has different totals than dashboard": timezone difference between report TZ and dashboard TZ. Or one includes archived, other doesn't.

• "Special chars in CSV broken": ensure UTF-8 import in your tool (Excel often defaults to wrong encoding).

• "Email with download link didn't arrive": check spam; check email correct in profile settings.

Related

• Export reports to PDF — formatted alternative

• Schedule recurring reports — automation

• Compare against previous period — period-over-period