# Obelism numbers

> Obelism numbers is the web analytics every Obelism product shares: visitors, sessions, page views, sources, campaigns, countries, devices, clicks on tagged elements and custom events, per space (one site) and environment (develop, staging, production). Sites send events with a script tag, the open source SDK `@obelism/numbers-sdk` or `POST /api/log`; Obelism Improve and Content send theirs too.

**When to use Obelism numbers**

Reach for numbers when a user wants to:

- Count a site's visitors, page views, sources and campaigns without a third-party analytics tool, and without storing IP addresses or query strings.
- Count clicks on buttons, links or sections (`data-numbers-id`) with a click rate, or track their own events (`sign_up`, `purchase`).
- See whether an Obelism Improve test's goal events arrive, or which Content blocks get clicked.

**How an agent should use it**

1. Pick the surface first: the script (`/script.js`) for a site without a build step; the SDK (`@obelism/numbers-sdk`) for anything with a bundler or router, analytics loaded behind consent, a stop/withdrawal, or your own page views and events. Both send the same events and reach the same reports. Then add it with the organization's id and the space id (`data-space` on the script). The dashboard's setup page has them, and a server's token is made there too. The site's origin must be allowed under Allowed origins on the space's page on www.obelism.studio.
2. To read reports, connect the MCP server (https://numbers.obelism.studio/mcp, OAuth, read-only) or call the agent API with a bearer token: `listOrganizations`, `listSpaces`, `getReport` and `listEvents`.
3. Errors are JSON problem details with a `code` and a `hint`; see the errors page.

## Docs

- [Agents and MCP](https://numbers.obelism.studio/docs/agents): Connect Claude, Codex, Cursor or any MCP client to numbers, and let it read your sites' visitors, pages, sources and events.
- [Agent API](https://numbers.obelism.studio/docs/api/agent): Read a Space's reports over HTTP with your Obelism session or an MCP token. The four read-only operations and their OpenAPI spec.
- [Errors](https://numbers.obelism.studio/docs/api/errors): Every error code numbers answers with, in RFC 9457 problem JSON, and what to change before retrying.
- [Sending events](https://numbers.obelism.studio/docs/api/log): 'POST /api/log: the endpoint the script and SDKs send to, and the one your server can call with an API token. The body, the headers and the answers.'
- [Add numbers to your site](https://numbers.obelism.studio/docs/getting-started): Choose the script or the SDK, allow your site's origin, and see the first visitors in the dashboard.
- [Obelism numbers](https://numbers.obelism.studio/docs): Web analytics every Obelism product shares. Visitors, pages, sources, campaigns, countries, devices, clicks and your own events, per site and environment.
- [Privacy & GDPR](https://numbers.obelism.studio/docs/privacy): What numbers stores about your visitors, what it leaves out, and how long it keeps it, for your own privacy policy and records.
- [Reports](https://numbers.obelism.studio/docs/reports): What every number in the numbers dashboard means, from visitors and sessions to bounce rate, sources, campaigns and click rate.
- [SDK](https://numbers.obelism.studio/docs/sdk): '@obelism/numbers-sdk: the numbers client as an npm package. Page views, clicks and events from an app with a bundler, per Space and environment.'
- [Clicks](https://numbers.obelism.studio/docs/tracking/clicks): Count clicks on buttons, links and sections by tagging them with data-numbers-id, and read each element's click rate.
- [Events](https://numbers.obelism.studio/docs/tracking/events): Send your own events, like sign_up or purchase, with a scope, a value and parameters. Naming, limits and what numbers does with them.
- [Page views](https://numbers.obelism.studio/docs/tracking/page-views): How the script and the SDK count page views, also on client-side navigations, and what a page view carries.
- [Visitors](https://numbers.obelism.studio/docs/tracking/visitors): How numbers tells visitors apart, what it knows about their device and country, and how a visitor is shared with Improve.

## API

- [OpenAPI spec](https://numbers.obelism.studio/openapi.json): OpenAPI 3.1 description of the read-only agent API

## Optional

- [Homepage](https://numbers.obelism.studio/index.md): what Obelism numbers is, what it counts and its FAQ, as Markdown
- [Agent setup](https://numbers.obelism.studio/agent-setup.md): instructions an agent follows to connect the numbers MCP server for its user
- [Full docs as text](https://numbers.obelism.studio/llms-full.txt): every docs page concatenated
- [Obelism](https://www.obelism.studio/llms.txt): every Obelism product, and which one to use
- [Sitemap](https://numbers.obelism.studio/sitemap.xml)