API overview

The REST API sends events and payments from your server, reads every dashboard report, and manages chart notes, funnels, segments, settings, alerts and team members. Everything the dashboard, the CLI and the MCP server show comes from these endpoints.

Base URL

Every path on these pages is relative to https://metricraven.com/api/v1. Send JSON request bodies with Content-Type: application/json; every response is JSON, except 204 No Content.

curl 'https://metricraven.com/api/v1/stats/traffic?range=all' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY"

Which key to use

Send a key as Authorization: Bearer …. How to create each one is in Authentication and access tokens.

The site parameter

• Account tokens must send exactly one site=WEBSITE_ID on every website endpoint. A missing, repeated or unknown site, or a website the token is limited away from, returns 401.
• Site secret keys already identify their website, so site is optional. If you send it, it must be that key's website ID; any other value returns 401.
• Website IDs look like ana_pub_1a2b3c4d5e6f7a8b. List yours with GET /websites.

Access levels

Each website endpoint needs one of four access levels. A credential that lacks it gets 401.

Reports read with a share link, or with a token without the visitors scope, return null instead of customer names, emails, user IDs and visitor IDs. An account token on a website where you are a viewer can read but never write, whatever its scopes.

Endpoints

Send data (secret key only)

Reports

Website configuration and people

Account (account tokens only)

Responses

Most endpoints return the object itself: a report, or a list under a named key such as { "notes": [...] } or { "funnels": [...] }. Alerts, notification preferences and team members wrap their result as { "status": "success", "data": ... }. Social mentions return data, pagination and meta.

• Timestamps are ISO 8601 strings in UTC. Chart notes use calendar dates (YYYY-MM-DD).
• Money is in major units of the report currency: 29 means $29.00. Rates and percentages are 0–100, rounded to two decimals.
• A change between periods is a relative percentage, or null when the previous value is zero.
• New fields can be added at any time; ignore those you don't know.

Errors

Errors have an HTTP status and a JSON body with a machine-readable error code. Many add a readable message; schema failures add details with the invalid fields.

{
  "error": "invalid_payload",
  "details": {
    "formErrors": [],
    "fieldErrors": { "currency": ["Invalid"] }
  }
}

Rate limits

Reports are cached for 60 seconds per website, range and parameter set, so polling faster than once a minute returns the same numbers. Add fresh=1 to recompute.

Pagination and list sizes

Paginated endpoints take offset (rows to skip, default 0) and limit (1–100, default 50) and return total, offset and nextOffset. nextOffset is null on the last page.

curl --get 'https://metricraven.com/api/v1/stats/breakdown' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY" \
  --data-urlencode 'range=all' \
  --data-urlencode 'dimension=page' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=100'

Date ranges and time zones

Reports that compare periods use the window of the same length that ends at from. Chart notes, the subscriptions report and realtime endpoints take no range.

Send crawler requests

POST /crawls records one request by a crawler that your server or edge middleware handled. Crawlers rarely run JavaScript, so this is how AI and search bots reach /stats/crawlers. Ready-made middleware is in Bots and AI crawlers.

curl --request POST 'https://metricraven.com/api/v1/crawls' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/pricing",
  "userAgent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
  "status": 200
}'

Crawler types are ai-training, ai-search, ai-assistant, search-engine, seo, social-preview and other. Requests for robots.txt, llms.txt, llms-full.txt, sitemaps and Markdown files are also counted as special files. Crawler requests are metered separately from events and are never refused for plan limits.