Get started with the Datasense API

Read analytics, list visitors, report payments and crawler requests from your own backend, scripts or AI agents.

Use the Datasense API to read analytics and send server-side events from your backend, scripts or AI agents. The MCP server exposes the same operations as tools.

Token	Use it for
`ds_sk_` website key	Read one website's analytics, visitors and errors, and report its payments
`ds_at_` account token	Read any of your websites (or a chosen few) with the permissions you pick; AI agents and scripts

Read authentication and scopes before giving a token to an agent.

Base URL

https://usedatasense.com/api/v1/

Authenticate requests

http

Authorization: Bearer YOUR_TOKEN

Create website keys in a website's Settings → API, and account tokens in API & MCP. Keep both secret: never put them in frontend code or public repositories.

Endpoints

Endpoint	Description
`GET /api/v1/account`	The caller's name, email and plan, with the plan's limits.
`GET /api/v1/websites`	The websites this credential can access, with their names, domains and timezones.
`GET /api/v1/websites/{websiteId}`	One website's settings: timezone, tracking mode, session replay, plan features and when its last event arrived.
`GET /api/v1/analytics/metadata`	Website display metadata: name, domain, timezone and reporting currency.
`GET /api/v1/analytics/overview`	Visitors, pageviews, sessions, bounce rate, session duration, revenue and conversion rate for a range, with the previous period of the same length and the change. The headline numbers on the dashboard.
`GET /api/v1/analytics/timeseries`	Visitors, pageviews and revenue per minute, hour, day, week or month.
`GET /api/v1/analytics/realtime`	Visitors online in the last 5 minutes, their top pages, referrers and countries, pageviews per minute for the last 30 minutes, and the latest pageviews and goals.
`GET /api/v1/analytics/realtime-map`	Visitors per country over the last 30 minutes, as on the live map.
`GET /api/v1/analytics/pages`	Top pages by visitors, with the revenue of sessions that landed on them. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/referrers`	Traffic sources: referrer domains, with Direct for visits without one. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/campaigns`	UTM campaigns (utm_campaign) by visitors and revenue. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/countries`	Visitors by country, as ISO codes. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/regions`	Visitors by region or state, labelled CC:Name. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/cities`	Visitors by city, labelled CC:Name. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/browsers`	Visitors by browser. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/operating-systems`	Visitors by operating system. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/devices`	Visitors by device type: Desktop, Mobile or Tablet. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/goals`	Goals and custom events with completions, unique visitors and conversion rate.
`GET /api/v1/errors`	JavaScript errors grouped by message, most frequent first, with counts, affected visitors, pages, browsers and the latest stack. Covers the website's latest 100 errors.
`GET /api/v1/bot-traffic/summary`	AI answer, indexing, training and other crawler requests, IP verification, providers and crawlers for a range. Pro and Team plans.
`GET /api/v1/bot-traffic/pages`	The pages crawlers request most, the discovery files they read (robots.txt, llms.txt, sitemaps, .md pages) and the pages that returned 404. Pro and Team plans.
`GET /api/v1/visitors`	Visitors in a range with their pageviews, sessions, time on site, source, location, device and lifetime revenue. Segment, sort and search them. Names and emails need the visitors:details permission.
`GET /api/v1/visitors/{visitorId}`	One visitor's profile: first touch, totals, goals, top pages and their latest sessions with every pageview, goal, payment and error. Identity needs visitors:details.
`POST /api/v1/payments`	Record a payment for revenue attribution.
`DELETE /api/v1/payments`	Delete a payment.
`POST /api/crawls`	Report a crawler request for bot traffic tracking.

Responses

Successful requests return 200 OK:

json

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

Errors

json

{
  "status": "error",
  "error": { "code": 403, "message": "This credential is missing the visitors:read permission." }
}

Code	Meaning	Common causes
`400`	Bad request	Invalid parameter, invalid date, startAt without endAt, missing websiteId
`401`	Unauthorized	Missing Authorization header, unknown or deleted token, an OAuth token used outside MCP
`402`	Payment required	This month's events are used up, so reports are locked until the 1st
`403`	Forbidden	Missing permission, a feature not on the plan, a website key used for another website
`404`	Not found	Unknown endpoint, or a website or visitor this token can't access
`429`	Rate limited	More than 60 requests a minute; see the X-RateLimit-* and Retry-After headers
`500`	Server error	Unexpected; retry shortly

The Payments API predates /api/v1 envelopes and answers { "message": … } or { "error": "…" }; see its pages.

Read this page as markdown llms.txt

Get started with the Datasense API

Read analytics, list visitors, report payments and crawler requests from your own backend, scripts or AI agents.

Use the Datasense API to read analytics and send server-side events from your backend, scripts or AI agents. The MCP server exposes the same operations as tools.

Token	Use it for
`ds_sk_` website key	Read one website's analytics, visitors and errors, and report its payments
`ds_at_` account token	Read any of your websites (or a chosen few) with the permissions you pick; AI agents and scripts

Read authentication and scopes before giving a token to an agent.

Base URL

https://usedatasense.com/api/v1/

Authenticate requests

http

Authorization: Bearer YOUR_TOKEN

Create website keys in a website's Settings → API, and account tokens in API & MCP. Keep both secret: never put them in frontend code or public repositories.

Endpoints

Endpoint	Description
`GET /api/v1/account`	The caller's name, email and plan, with the plan's limits.
`GET /api/v1/websites`	The websites this credential can access, with their names, domains and timezones.
`GET /api/v1/websites/{websiteId}`	One website's settings: timezone, tracking mode, session replay, plan features and when its last event arrived.
`GET /api/v1/analytics/metadata`	Website display metadata: name, domain, timezone and reporting currency.
`GET /api/v1/analytics/overview`	Visitors, pageviews, sessions, bounce rate, session duration, revenue and conversion rate for a range, with the previous period of the same length and the change. The headline numbers on the dashboard.
`GET /api/v1/analytics/timeseries`	Visitors, pageviews and revenue per minute, hour, day, week or month.
`GET /api/v1/analytics/realtime`	Visitors online in the last 5 minutes, their top pages, referrers and countries, pageviews per minute for the last 30 minutes, and the latest pageviews and goals.
`GET /api/v1/analytics/realtime-map`	Visitors per country over the last 30 minutes, as on the live map.
`GET /api/v1/analytics/pages`	Top pages by visitors, with the revenue of sessions that landed on them. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/referrers`	Traffic sources: referrer domains, with Direct for visits without one. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/campaigns`	UTM campaigns (utm_campaign) by visitors and revenue. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/countries`	Visitors by country, as ISO codes. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/regions`	Visitors by region or state, labelled CC:Name. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/cities`	Visitors by city, labelled CC:Name. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/browsers`	Visitors by browser. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/operating-systems`	Visitors by operating system. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/devices`	Visitors by device type: Desktop, Mobile or Tablet. Each row has visitors, pageviews and revenue attributed to sessions that started there.
`GET /api/v1/analytics/goals`	Goals and custom events with completions, unique visitors and conversion rate.
`GET /api/v1/errors`	JavaScript errors grouped by message, most frequent first, with counts, affected visitors, pages, browsers and the latest stack. Covers the website's latest 100 errors.
`GET /api/v1/bot-traffic/summary`	AI answer, indexing, training and other crawler requests, IP verification, providers and crawlers for a range. Pro and Team plans.
`GET /api/v1/bot-traffic/pages`	The pages crawlers request most, the discovery files they read (robots.txt, llms.txt, sitemaps, .md pages) and the pages that returned 404. Pro and Team plans.
`GET /api/v1/visitors`	Visitors in a range with their pageviews, sessions, time on site, source, location, device and lifetime revenue. Segment, sort and search them. Names and emails need the visitors:details permission.
`GET /api/v1/visitors/{visitorId}`	One visitor's profile: first touch, totals, goals, top pages and their latest sessions with every pageview, goal, payment and error. Identity needs visitors:details.
`POST /api/v1/payments`	Record a payment for revenue attribution.
`DELETE /api/v1/payments`	Delete a payment.
`POST /api/crawls`	Report a crawler request for bot traffic tracking.

Responses

Successful requests return 200 OK:

json

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

Errors

json

{
  "status": "error",
  "error": { "code": 403, "message": "This credential is missing the visitors:read permission." }
}

Code	Meaning	Common causes
`400`	Bad request	Invalid parameter, invalid date, startAt without endAt, missing websiteId
`401`	Unauthorized	Missing Authorization header, unknown or deleted token, an OAuth token used outside MCP
`402`	Payment required	This month's events are used up, so reports are locked until the 1st
`403`	Forbidden	Missing permission, a feature not on the plan, a website key used for another website
`404`	Not found	Unknown endpoint, or a website or visitor this token can't access
`429`	Rate limited	More than 60 requests a minute; see the X-RateLimit-* and Retry-After headers
`500`	Server error	Unexpected; retry shortly

The Payments API predates /api/v1 envelopes and answers { "message": … } or { "error": "…" }; see its pages.