Export PDF / CSV reports

POST /api/v1/analytics/export (verified apps/backend/src/routes/api/analytics/export.route.ts) → 202 Accepted + job_id. Poll GET /api/v1/analytics/export/:job_id until complete. Formats: CSV (raw data) + PDF (formatted report). Constraints: 90-day max date range, active subscription required. Async via SQS WorkerType.EXPORT_UNIFIED_REPORT + job_result table tracks status.

Who is this for

Mediabuyers + admins producing reports for clients / leadership / external stakeholders. Anyone needing analytics data outside Wevion's UI (in BI tools, spreadsheets, presentations).

How to export

Step 1: Configure your view

Open /analytics → pick mode (Single Platform / Cross-Channel) → set date range, platforms, target_currency, comparison toggle. The export reflects this configuration.

Step 2: Click Export

Top-right toolbar → Export → pick format (CSV or PDF).

Step 3: Job submitted

UI shows toast "Report queued — we'll email when ready". POST /api/v1/analytics/export runs → returns 202 + job_id.

Step 4: Wait / poll

The export runs asynchronously via SQS. Typical times:

For Cross-Channel exports: 90-day hard limit (MAX_DATE_RANGE_DAYS = 90).

Step 5: Email + UI

Once complete:

• Email arrives with download link (valid 7 days)

• Reports section shows the file in Recent exports

• Click → download

Endpoint

POST /api/v1/analytics/export (verified):

Body:

• format: csv or pdf

• mode: single_platform or cross_channel

• Date range + scope params (same as the view you're exporting)

Returns 202 Accepted + {job_id, status: "pending"}.

GET /api/v1/analytics/export/:job_id (verified):

Returns the job_result row:

• status: pending / running / completed / failed

• data: URL to download (when completed)

• error: message (when failed)

• created_at, completed_at

CSV vs PDF — when to use which

PDF wins on presentation; CSV wins on data manipulation.

(Similar to Ads Manager am-116 + am-117 for row-level reports — Analytics export is the aggregated companion.)

What's in each format

CSV

• UTF-8 encoded

• Comma-separated

• One row per entity per date OR aggregated (configurable)

• Headers: include all selected metrics + dimensions

Example header for Cross-Channel:

date,platform,spend,impressions,clicks,ctr,cpc,cpm,conversions,roas,cpa

PDF

Standard sections:

1. Cover page (workspace + date range + generated timestamp)

2. Executive summary (KPI strip)

3. Per-platform breakdown

4. Channel mix donut

5. Top campaigns

6. Comparison vs previous period (if enabled)

7. Appendix (filters + date range exact + currency notes)

Workspace branding (logo, colors) applied if configured.

Subscription requirement

Export requires an active subscription (see acc-* billing):

• Workspaces without active subscription: export returns 403 with reason "subscription_required"

• Plan tier may limit: number of exports per month, scheduled exports, custom branding

Check your plan at /settings/team/billing.

90-day max date range

Hard constraint inherited from Cross-Channel:

• Date range cap: 90 days

• Larger ranges: request rejected with clear error

• Workaround: split into 2-3 calls, concatenate externally

This applies to both Single Platform + Cross-Channel exports (the export pipeline is unified — EXPORT_UNIFIED_REPORT SQS worker type).

Email delivery

Once the job completes:

• Email sent to workspace billing email (or per-user notification email if configured)

• Subject: "Wevion Analytics Report — [Period] — [Workspace]"

• Body: brief summary + download link

• Download link valid: 7 days

Recipients can:

• Read email + headline metrics

• Download attachment (or fetch from link for larger reports)

Tracking + history

Reports section in /analytics (or admin view) shows:

• All recent export jobs with status

• Per-job download link (if completed)

• Per-job error message (if failed)

• Filter by date / format

Async via SQS

Behind the scenes:

1. POST triggers SQS message → EXPORT_UNIFIED_REPORT worker type

2. Worker runs query + formats output (CSV / PDF)

3. Stores result file in S3 (or equivalent)

4. Writes job_result row with status + download URL

5. Sends email notification

Worker scaling: handles multiple concurrent exports; bounded by SQS in-flight cap + S3 throughput.

Common mistakes

• Date range > 90 days: rejected; split or use narrower window

• Exporting without active subscription: 403; check /settings/team/billing

• Expecting synchronous download: it's async — wait for email or poll job

• Sharing download URL beyond 7-day validity: link expires; re-export if needed

• Format mismatch for use case: PDF for spreadsheet analysis = painful; CSV for client presentation = unpolished

Common issues

• Job stuck pending > 10 min: SQS worker backlog; usually self-resolves; if persistent contact admin

• Job failed with no clear error: check error field in job_result; common: timeout on very large datasets; reduce scope

• Email not arriving: check spam; verify email in profile; large attachments may go to large-mail queue

• PDF missing branding: workspace branding not configured (see am-117 templates)

• CSV totals differ from on-screen: may be export aggregation vs view aggregation difference; verify scope params

Related

• Ads Manager CSV export — row-level companion

• Ads Manager PDF export — row-level PDF

• Analytics troubleshooting — debugging exports