API reference

Visitors and people API

On this page

Search visitors
Visitor profile
Erase a person
Details

These endpoints return or delete data about individual people, so share links can never use them. Read them with the site secret key or an account token with the visitors scope.

Request	Use it for
GET /stats/visitors	Search visitors in a period
GET /stats/journeys	People who paid or completed a goal
GET /visitors/VISITOR_ID	One person's profile and complete timeline (below).
DELETE /people	Erase one person (below).
DELETE /payments, DELETE /events	Delete payments or goal events

Search visitors

GET /stats/visitors lists the period's visitors (see the Reports API for the period, paging and response). Besides the JSON filters, it takes plain search parameters; each becomes one filter, all must match, and comma-separated values match any of them. At most six filters apply in total.

Parameter	Matches visitors who…
visitedPage (page)	Viewed this exact path, e.g. /pricing.
visitedPageContains (pageContains)	Viewed a path containing this text, without case.
entryPage	Started their first visit in the period on this path.
completedGoal (goal)	Completed this goal in the period.
referrer	Came from a referrer containing this text, e.g. google.
channel	Arrived first through this channel: Direct, Organic Search, Social, Referral, Email, Paid…
utm_source, utm_medium, utm_campaign, utm_term, utm_content	Had a pageview with these UTM tags.
ref, source, via	Had a pageview with these link tags (?ref=, ?source=, ?via=).
country, region, city	Were located there; country takes two-letter codes.
browser, os, device, hostname	Used this browser, OS, device (desktop, mobile, tablet) or hostname.
visitType	new (first pageview ever in the period) or returning.
visits_gt, visits_lt, visits	Made more than, fewer than or exactly this many visits in the period. A visit ends after 30 minutes without a pageview.

terminal

curl 'https://metricraven.com/api/v1/stats/visitors?range=all&visitedPage=/pricing&completedGoal=signup&visits_gt=2' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY"

The response's filters lists every filter that applied. An invalid value, or more than six filters, returns 400 invalid_visitor_query with a message. The same numeric filter works in every report's filters as {"dim":"visits","op":"gt","values":["2"]} (ops gt, lt, is, is_not).

Visitor profile

GET /visitors/VISITOR_ID returns everything known about one person: every visitor ID linked to the same user by identify, their visits, goals, sign-ins and payments. It takes no period and is never cached.

terminal

curl 'https://metricraven.com/api/v1/visitors/0123456789abcdef0123456789abcdef' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY"

Response

{
  "visitorId": "0123456789abcdef0123456789abcdef",
  "visitorIds": ["0123456789abcdef0123456789abcdef", "fedcba9876543210fedcba98"],
  "user": {
    "userId": "user_42",
    "email": "ana@example.com",
    "name": "Ana",
    "traits": { "plan": "pro" },
    "verified": true
  },
  "summary": {
    "firstSeenAt": "2026-10-01T09:14:02.000Z",
    "lastSeenAt": "2026-10-03T18:40:11.000Z",
    "visits": 3,
    "pageviews": 9,
    "events": 2,
    "timeOnSite": 412,
    "spent": 29,
    "firstTouch": { "source": "google.com", "channel": "Organic Search", "landingPage": "/", "at": "2026-10-01T09:14:02.000Z" },
    "device": { "browser": "Chrome", "os": "macOS", "deviceType": "desktop", "app": null },
    "location": { "country": "US", "region": "California", "city": "San Francisco" }
  },
  "timeline": [
    { "type": "pageview", "at": "2026-10-01T09:14:02.000Z", "path": "/", "newVisit": true, "source": "google.com", "channel": "Organic Search" },
    { "type": "event", "at": "2026-10-01T09:16:40.000Z", "name": "signup", "path": "/signup", "props": { "plan": "free" }, "newVisit": false },
    { "type": "identify", "at": "2026-10-01T09:16:41.000Z", "email": "ana@example.com" },
    { "type": "payment", "at": "2026-10-03T18:40:11.000Z", "amount": 29, "currency": "USD", "plan": "pro", "renewal": false, "refunded": false, "refundedAmount": 0 }
  ]
}

Field	Meaning
visitorIds	The requested ID plus every visitor ID identified as the same user.
user	null for anonymous visitors. Otherwise userId, email, name, custom traits and verified: true when the identity came from your server, false when only the browser claimed it.
summary	firstSeenAt, lastSeenAt, visits (a new visit after 30 minutes of inactivity), pageviews, events, timeOnSite (seconds visible), spent (net of refunds, all currencies added), firstTouch, device (app has id and version for native apps) and location of the latest located event.
timeline[]	Oldest first. pageview (path, newVisit, and source and channel when it starts a visit), event (name, path, props, newVisit), identify (email) and payment (amount, currency, plan, renewal, refunded, refundedAmount).

Visitor IDs are 24 (daily, before consent) or 32 (persistent) lowercase hex characters; anything else returns 400 invalid_visitor_id. An ID with no events, payments or identity returns 404 not_found.

Erase a person

DELETE /people handles a deletion request: it deletes the person's events and identity links and keeps their payments in revenue totals without any link to them. It accepts only the site secret key or a signed-in admin; account tokens get 403 so an assistant can never erase data. Dashboard steps are in Delete a person's data.

Field	Type	Description
user_id	string	Your application's user ID (1–200 characters).
visitor_id	string	A visitor ID.
email	string	An email sent with identify; matched without case to the user IDs it was identified as.

Send at least one. Every visitor ID linked to the user IDs found is erased too.

terminal

curl --request DELETE 'https://metricraven.com/api/v1/people' \
  --header "Authorization: Bearer $METRICRAVEN_SECRET_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "ana@example.com"
}'

Response

{
  "ok": true,
  "visitorIds": 2,
  "deleted": { "events": 41, "identities": 2 },
  "anonymizedPayments": 1
}

Status	Meaning
400 invalid_request	No user_id, visitor_id or email, or an invalid one.
403 forbidden	Called with an account token.
404 not_found	Only an email was sent and nobody was identified with it.

Erasure can't be undone. Payments stay, but their visitor, user and customer IDs are removed.

Details

Reports read with a token without the visitors scope, or with a share link, return null for names, emails, user IDs and visitor IDs.
A browser identify is self-asserted until your server confirms it with POST /identify; verified tells them apart.