Skip to content
DocsExports and the API

Exports and the read API

Every report on the dashboard can leave it: as a CSV download, or as JSON or CSV from your own scripts with a read-only key.

Download CSV

Open Exports & API for a verified site, pick a period, and download any report. Files hold aggregated figures, up to 200 rows per report. Daily uniques count each day separately.

Create a read key

On the same page, an owner or admin of a verified site can create a key and give it a name. The key is shown once, so copy it then. It starts with mf_read_.

  • A key reads the aggregated reports of one website. It can’t write anything.
  • Each site can have five active keys. Revoke one to make room; revocation takes effect on the next request.
  • Keep keys in your server’s environment. Never put one in a public website script: the API doesn’t accept browser requests from other origins.

Make a request

Request
curl 'https://getmayfly.com/api/v1/sites/YOUR_SITE_ID/reports/pages?period=30d' \
  -H 'Authorization: Bearer YOUR_READ_KEY'

GET /api/v1/sites/{siteId}/reports/{report} with these query parameters:

  • period: 24h, 7d, 30d, 90d or 12m. The default is 30d.
  • format: json (the default) or csv.

Reports:

  • overview Overview
  • pages Pages
  • sources Sources
  • channels Channels
  • referrers Referrers
  • campaigns Campaigns
  • countries Countries
  • regions Regions
  • cities Cities
  • browsers Browsers
  • systems Operating systems
  • devices Devices
  • hostnames Hostnames
  • outbound Outbound clicks
  • vitals Core Web Vitals
  • goals Goals
  • search Search queries

The response

JSON response, shortened
{
  "rows": [{ "path": "/pricing", "dailyUniques": 412, "pageviews": 530, … }],
  "columns": ["path", "dailyUniques", "pageviews", "avgSeconds", "avgScroll", "entries", "bounceRate"],
  "meta": {
    "report": "pages", "period": "30d", "timezone": "Europe/London",
    "from": "…", "to": "…", "rowLimit": 200, "possiblyTruncated": false, "approximate": false, …
  }
}

JSON carries rows, columns and meta. meta states the window (start included, end excluded), the site and source timezones, the row limit, and whether the result is approximate or possibly cut short. CSV responses carry the same facts in x-mayfly-* headers. Revenue is in minor units, and mixed currencies are flagged rather than added up.

Limits and errors

StatusMeaning
400An unsupported period or format.
401No key or session, or a malformed Authorization header.
404Unknown report, or the key doesn’t belong to this site or was revoked.
409The website isn’t verified yet.
422The export would exceed 2 MB. Choose a shorter period.
429Too many requests. Each site allows 30 a minute. Follow Retry-After.
503Temporarily unavailable. Try again.

Stripe payment report

If you use the Stripe payment report, the site’s owner can create a key that may also read it, at reports/payments?period=30d&mode=live. Payment reports support 7d and 30d, in test or live mode. Existing keys don’t gain this access.

Something here doesn’t match what you see? Write to kirylapps@gmail.com.