---
title: Read API
description: Read a website's traffic and A/B results from your server.
aliases: [api, read api, analytics api, query api, twocms, /query/analytics, /query/ab]
---

Two endpoints answer a website's numbers as JSON, for your own backend. They use the website's [API token](/docs/analytics/server-events#your-api-token), so call them from a server only: browsers cannot read them.

```
GET https://app.blueradar.net/api/v1/websites/{site_id}/analytics
GET https://app.blueradar.net/api/v1/websites/{site_id}/ab
```

`{site_id}` is the website's site ID.

## Authentication

Send the token as a bearer token:

```bash
curl https://app.blueradar.net/api/v1/websites/YOUR_SITE_ID/ab?start_date=2026-11-01&end_date=2026-11-07 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Dates

| Parameter | |
| --- | --- |
| `start_date` | First day, `YYYY-MM-DD` in UTC. Today when left out |
| `end_date` | Last day, included, `YYYY-MM-DD` in UTC. Today when left out |

## Traffic

`/analytics` answers:

```json
{
  "overview": {"total_pageviews": 120, "total_visitors": 80,
    "change": {"pageviews_percent": 20, "visitors_percent": null}, "has_previous_data": true},
  "timeseries": {"granularity": "daily",
    "data": [{"timestamp": "2026-11-01", "pageviews": 10, "visitors": 7}],
    "pageviews": [{"timestamp": "2026-11-01", "value": 10}],
    "visitors": [{"timestamp": "2026-11-01", "value": 7}]},
  "top_pages": [{"path": "/", "pageviews": 70, "visitors": 47}],
  "top_referrers": [{"referrer_name": "google.com", "referrer_url": null, "pageviews": 30, "visitors": 20}],
  "top_countries": [{"country": "AU", "pageviews": 90, "visitors": 60}],
  "browsers": [{"browser": "Chrome", "pageviews": 100, "visitors": 67}],
  "os": [{"os": "macOS", "pageviews": 80, "visitors": 53}],
  "visitors_estimated": {"rows": true, "timeseries": false},
  "visitors_unavailable": false,
  "nothing_known": false
}
```

- `change` compares with the same number of days before `start_date`.
- `granularity` is `hourly` up to 3 days, `daily` up to 91, then `weekly` and `monthly`. Times are UTC.
- Top lists hold up to 10 rows by pageviews.
- A row's `visitors` is an estimate: visitors are counted for the whole website, not per page, source, country, browser or OS. It is the row's pageviews times the website's visitors per pageview, rounded, at least 1, and never more than the row's pageviews or `total_visitors`. Sort and share rows by `pageviews` when you need exact numbers.
- A `weekly` or `monthly` point's `visitors` is an estimate too: visitors are counted per day at most, and someone who visits on two days of a week is one visitor that week. It is the sum of the bucket's daily visitors, scaled so all buckets add up to the range's visitors, and kept between the bucket's busiest day and that sum. `hourly` and `daily` points are exact.
- `visitors_estimated` says which of the two apply.
- Visitors can be unavailable: for some older hours Blue Radar knows pageviews but cannot count distinct visitors. Then `total_visitors`, `change.visitors_percent` and every row's `visitors` are `null` (never `0`), and `visitors_unavailable` is `true`. A point's `visitors` is `null` when its own bucket cannot be counted, even if the range can; a `weekly` or `monthly` point is `null` when any of its days is. Pageviews are always numbers.
- `nothing_known` is `true` when Blue Radar holds no data at all for the period (before your data starts, or before the retention limit). The numbers are then zeros; show "No data for this period" rather than "0 pageviews". The A/B answer carries the same flag.
- Direct traffic is the referrer with an empty `referrer_name`.

## A/B results

`/ab` answers:

```json
{
  "event_names": ["signup"],
  "rows": [
    {"variant": "hero-b", "unique_visitors": 388, "events": {"signup": 31}},
    {"variant": "hero-a", "unique_visitors": 380, "events": {}}
  ]
}
```

Rows are ordered by visitors. `events` adds up each event's values, 1 for an event sent without one. See [A/B tests](/docs/analytics/ab-tests).

## Errors

Errors are JSON with an `error` message.

| Status | Meaning |
| --- | --- |
| 401 | The token is missing, wrong or was rotated, or no website has this site ID |
| 404 | The website was revoked |
| 429 | Too many requests. Wait for `Retry-After` seconds |
| 500 | The numbers could not be read, try again |
