REST API v1

The REST API lets your servers, scripts and AI agents read your analytics and send events. All endpoints live under https://dataeasy.app/api/v1 and are authenticated with a Bearer token.

Authentication

Credential	Where to create it	Scope
`de_live_…`	Website settings → API	One website, every analytics and ingestion endpoint. Not the admin endpoints.
`de_pat_…`	Account settings → API & MCP	The websites you pick (or all), limited to the permissions you tick. Also works with the MCP server.

curl "https://dataeasy.app/api/v1/analytics/overview?period=last7d" \
  -H "Authorization: Bearer de_live_…"

With an access token that covers several websites, pass websiteId (the website id or its public deid_… id). Tokens need the matching permission, e.g. analytics:read for the analytics endpoints or goals:write to send goals; a write permission includes read.

Responses

Success / error

{ "status": "success", "data": { … } }

{ "status": "error", "error": { "code": "forbidden", "message": "This token lacks the goals:write permission" } }

Error codes: bad_request (400), unauthorized (401), forbidden (403), not_found (404), rate_limited (429). Each credential can make 600 requests per minute; every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. GET endpoints allow CORS from any origin, but keep your token on the server.

Read endpoints

GET /api/v1…	Returns
`/analytics/overview`	Totals for the period (visitors, sessions, pageviews, bounce rate, revenue, customers, conversion rate) and % change.
`/analytics/timeseries`	Metrics per bucket. compare=true adds the previous period.
`/analytics/realtime`	Visitors in the last 5 minutes, per-minute visitors for the last 30 minutes, top countries.
`/analytics/realtime/map`	Live visitors with location, system and current page.
`/analytics/metadata`	Website settings: domain, timezone, currency, first and last event.
`/analytics/goals`	Goals with completions, visitors and conversion rate.
`/analytics/referrers, /channels, /campaigns`	Traffic sources.
`/analytics/pages, /entry-pages, /hostnames`	Pages.
`/analytics/countries, /regions, /cities`	Locations.
`/analytics/browsers, /operating-systems, /devices`	Systems.
`/analytics/exit-clicks`	Outbound links clicked.
`/analytics/payments`	Payments (converted visitors) in the period.
`/analytics/funnels, /funnels/{funnelId}`	Funnel step counts and conversion between steps.
`/analytics/bot-traffic, /bot-traffic/pages`	AI crawler hits by crawler, category and page.
`/visitors/{visitorId}`	One visitor: first/last seen, location, acquisition, pages, goals, payments and identity.

Query parameters

The same as the dashboard API: period, granularity, timezone, offset (periods back), hostname and every filter (country, referrer, path, utm_source…). Breakdowns are paginated with limit (1–1000, default 100) and page. Money is in major units of the website currency and rates are percentages.

GET /api/v1/analytics/countries?period=last7d&limit=1

{
  "status": "success",
  "data": {
    "websiteId": "6f1d…",
    "period": "last7d",
    "timezone": "Europe/Rome",
    "currency": "USD",
    "breakdown": "countries",
    "total": 42,
    "page": 1,
    "limit": 1,
    "hasMore": true,
    "data": [
      { "name": "United States", "countryCode": "US", "visitors": 1602, "revenue": 1493,
        "payments": 9, "conversionRate": 0.56, "goalCompletions": 162 }
    ]
  }
}

Send events from your server

POST /api/v1…	Body	Permission
`/goals`	`{ visitor_id, name, metadata? }`	`goals:write`
`/payments`	`{ visitor_id, amount, currency, transaction_id, customer_email?, renewal?, refunded? }`	`payments:write`
`/identify`	`{ visitor_id, user_id, name?, email?, metadata? }`	`identify:write`

visitor_id is the value of the dataeasy_visitor_id cookie. Goals are attached to the visitor's latest session, payments are deduplicated by transaction_id, and identities show up on /visitors/{visitorId}.

curl -X POST https://dataeasy.app/api/v1/goals \
  -H "Authorization: Bearer de_live_…" \
  -H "Content-Type: application/json" \
  -d '{"visitor_id":"v_3f2a…","name":"signup","metadata":{"plan":"pro"}}'

Admin endpoints

Personal access tokens can also manage websites under /api/v1/admin: websites (list, create, read, update, delete) and, per website, team, goals, funnels, alerts, apikeys and integrations, plus account and access-tokens. Each requires the matching permission and your role on the website (viewers can't change settings).

Prefer asking questions in plain English? The same data is available to AI assistants through the MCP server.

✍️ Something missing? Tell us.

🧭 New to DataEasy? Start with the introduction