API reference
The Pageviews API is a read-only analytics API for accessing your website traffic data programmatically. All endpoints require authentication with a valid API token.
Base URL
https://pageviews.ai/api/v1Authentication
All requests must include your API token in the Authorization header:
Authorization: Bearer your-api-token-hereAPI access is available on plans with the API Access feature enabled. Requests without a valid token receive a 401 Unauthenticated response. Requests from plans without API access receive a 403 Forbidden response.
Rate limiting
API requests are rate-limited to 600 requests per minute per token. If you exceed this limit, you'll receive a 429 Too Many Requests response. Wait and retry after the rate limit window resets.
Common query parameters
All analytics endpoints share the following query parameters:
| Parameter | Required | Description |
|---|---|---|
from | Yes | Start date, inclusive (format: YYYY-MM-DD) |
to | Yes | End date, inclusive (must be on or after from) |
period | No | Time grouping: day, week, or month. Default: day. Only used by the stats endpoint. |
compare_from | No | Comparison period start date |
compare_to | No | Comparison period end date (required when compare_from is set) |
timezone | No | IANA timezone for date calculations (e.g., Europe/Berlin). Defaults to the site's configured timezone. |
filters | No | JSON-encoded array of filter objects (see Filtering below) |
Filtering
The filters parameter accepts a JSON-encoded array of filter objects:
[{"field": "country", "op": "=", "values": ["US", "GB"]}]Available filter fields
country, city, browser, os, device_type, utm_campaign
Custom properties can be filtered using the prop: prefix (e.g., prop:plan_name).
Filter operators
| Operator | Meaning |
|---|---|
= | Equals |
!= | Not equals |
contains | Contains (LIKE) |
not_contains | Not contains (NOT LIKE) |
< | Less than |
<= | Less than or equal |
> | Greater than |
>= | Greater than or equal |
Response format
All responses are in JSON format. Successful responses return a 200 status code with data wrapped in a data object. Error responses include a descriptive message.
Error responses
| Status | Description |
|---|---|
401 | Missing or invalid API token |
403 | Plan does not include API access, or no access to the site |
422 | Invalid query parameters (includes validation error details) |
429 | Rate limit exceeded |