API reference

Reports API

On this page

Make your first request
Common parameters
Endpoints
Filters
Saved segments
Details

Call reports from your backend with the site secret. All paths begin with https://metricraven.com/api/v1.

Make your first request

Set METRICRAVEN_SECRET_KEY on your server
Never call these endpoints from browser code.

Request a report

Replace the dates with your window, using full ISO timestamps including the time zone. Or use range=all without dates for all retained history.

terminal

curl --get 'https://metricraven.com/api/v1/stats/traffic' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY" \
  --data-urlencode 'from=2026-10-01T00:00:00.000Z' \
  --data-urlencode 'to=2026-10-30T23:59:59.000Z' \
  --data-urlencode 'granularity=day' \
  --data-urlencode 'currency=USD'

Common parameters

Parameter	Meaning
from, to	ISO timestamps with time zone; from must be before to, at most 36,600 days apart.
range=all	All retained history instead of from/to; the server resolves its real start and current end.
granularity	hour \| day \| week \| month. Hourly becomes daily for ranges over three days.
currency	For example USD.
timezone	Optional IANA identifier (default UTC) for calendar grouping, returned in period.timeZone.
filters	Up to six visitor filters encoded as JSON (see below).
fresh=1	Bypass the short report cache.

Endpoints

Path	Returns
/stats/traffic	Traffic totals, time series and breakdowns. primaryGoal is null by default, or contains name, current/previous converted visitors, visitors, rate and relative percentage changes for the configured goal. Rates are null when the visitor denominator is zero.
/stats/breakdown?dimension=referrer	Complete traffic breakdown; supports q, sort=visitors\|pageviews\|revenue, offset and limit (1–100). Returns total and nextOffset; outbound links do not support revenue sorting.
/stats/conversions	Goals, customers and funnel steps.
/stats/visitors	Private period visitor search. Supports q, payment=all\|paid\|unpaid, sort=latest\|earliest\|pageviews, offset and limit (1–100); returns total and nextOffset. Requires site membership or the secret key; share links are denied. Responses are not cached.
/stats/insights	Aggregate buyer rates, complete cohort rankings, first-observed purchase timing, reporting-zone purchase heatmap and source changes.
/stats/revenue	Payments, renewals, refunds and lifetime value.
/stats/search	Search Console queries and pages.
/stats/crawlers	Bot and AI crawler requests.
/stats/filter-values?dimension=country	Search all aggregate filter values; supports q, offset and limit (1–100).
/stats/goal?name=signup	One goal, its properties and sources.
/stats/live	Live visitors; does not require a date range.

Filters

Encode a JSON array as the filters query parameter. Operators are is, is_not, contains and not_contains.

Example filters parameter

[
  { "dim": "country", "op": "is", "values": ["US", "GB"] },
  { "dim": "page", "op": "not_contains", "values": ["/admin"] }
]

dimension=hostname: recorded page hostnames. dimension=campaignTuple: complete UTM combinations, in breakdown and filter-value requests.
Referral parameter dimensions are linkRef, linkSource and linkVia; refTag is the primary referral tag.

Saved segments

Request	Body
GET /segments	None.
POST /segments	JSON with name and filters.
PUT /segments/SEGMENT_ID	The current revision, name and full filters.
DELETE /segments/SEGMENT_ID	JSON with the current revision.

A stale revision returns HTTP 409; read the latest list before retrying. These endpoints require a site secret or member session, are unavailable to share links and take no date range.

Details

Long windows use coarser intervals to keep charts bounded.
Exact from/to timestamps stay instants; the timezone controls calendar grouping. Invalid zones are rejected. Non-UTC hourly keys include an offset, for example 2026-10-25T02:00+0200 and 2026-10-25T02:00+0100 are separate groups. Search Console always reports its own Pacific calendar window.
Traffic, breakdown, insights, conversions, goal and journey reports accept filters. Each filter supports up to 20 values; the full filters parameter is limited to 16,000 characters.
Existing {"dim":"country","value":"US"} filters still work.
Filter-value search respects other dimensions and ignores filters on the dimension being edited; its results contain only values and aggregate visitor counts.
A campaign row's name is the canonical JSON array of source, medium, campaign, term and content, with null for absent tags. Reuse that exact string as a campaignTuple filter value. Combination filters accept only is and is_not; matching all five tags on one pageview prevents combinations assembled from different visits.
refTag includes older combined records. All referral dimensions support the normal exact, negative and literal contains operators.