/Docs
Register

Project API

Read and update a project — details, analytics, custom events, goals, bot traffic, install checks, and CSV export.

ℹ
Replace {domain} in each endpoint with your project's domain, e.g. example.com. All endpoints require a Bearer token; see Authentication. Goals and bots prefer a session Bearer (API keys may get empty results); events and export work with an API key.
GET/api/v1/projects/{domain}

Returns project details: name, timezone, public stats flag, brand color, icon, install timestamp, and whether the caller is the owner.

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const project = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "id": "44cc0aa0-912f-4067-83c7",  "name": "Madar Agency",  "domain": "example.com",  "timeZone": "Africa/Casablanca",  "publicStatsEnabled": false,  "brandColor": "#FF6A00",  "icon": null,  "installationSeenAt": "2026-05-01T12:00:00.000Z",  "createdAt": "2026-04-01T12:00:00.000Z",  "isOwner": true}

Response fields

id

string

Unique project identifier.

name

string

Project display name.

domain

string

Normalized project domain.

timeZone

string

IANA timezone used for reporting.

publicStatsEnabled

boolean

Whether the public stats page is enabled.

brandColor

string | null

Optional brand hex color.

icon

string | null

Optional project icon URL.

installationSeenAt

string | null

ISO timestamp when the tracker was first seen, or null.

createdAt

string

ISO timestamp when the project was created.

isOwner

boolean

True when the authenticated user owns the project.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

PATCH/api/v1/projects/{domain}

Updates project settings. Requires a write-scoped API key and project ownership. Pass any combination of name, timeZone, and publicStatsEnabled.

Parameters

nameoptional

New display name (max 80 characters).

string

timeZoneoptional

Valid IANA timezone, e.g. America/New_York.

string

publicStatsEnabledoptional

Enable or disable the public stats page.

boolean

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com", {  method: "PATCH",  headers: {    Authorization: `Bearer ${OPENREVENUE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({ name: "Example", publicStatsEnabled: true }),}) const updated = await res.json()

cURL

bash
curl -X PATCH "https://api.openrevenue.com/api/v1/projects/example.com" \  -H "Authorization: Bearer openrevenue_your_key" \  -H "Content-Type: application/json" \  -d '{ "name": "Example", "publicStatsEnabled": true }'

Response

json
{  "id": "44cc0aa0-912f-4067-83c7",  "name": "Example",  "domain": "example.com",  "timeZone": "Africa/Casablanca",  "publicStatsEnabled": true,  "installationSeenAt": "2026-05-01T12:00:00.000Z"}

Response fields

id

string

Unique project identifier.

name

string

Updated display name.

domain

string

Normalized project domain.

timeZone

string

IANA timezone after the update.

publicStatsEnabled

boolean

Public stats setting after the update.

installationSeenAt

string | null

ISO timestamp when the tracker was first seen, or null.

Errors

400
No valid fields to update

The body had no recognized fields, or values failed validation.

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

403
API key is read-only

The key does not include the write scope.

404
Project not found

No project with that domain exists for the owner, or the caller is not the owner.

429
Too many requests

Rate limit exceeded.

GET/api/v1/projects/{domain}/stats

Returns aggregate stats for a project over the given period: total pageviews, unique visitors, sessions, and average session duration in seconds.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/stats?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const stats = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/stats?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "pageviews": 130,  "visitors": 35,  "sessions": 48,  "avgDurationSeconds": 94}

Response fields

period

string

Resolved reporting period.

pageviews

number

Total pageview events in the period.

visitors

number

Unique visitors in the period.

sessions

number

Unique browser sessions in the period.

avgDurationSeconds

number | null

Average visit duration from leave events, in seconds.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/timeseries

Returns pageviews and unique visitors bucketed over time. Granularity is hourly for the 24h period and daily for all others.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/timeseries?period=7d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const timeseries = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/timeseries?period=7d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "7d",  "granularity": "day",  "data": [    { "date": "2026-05-19T00:00:00.000Z", "pageviews": 18, "visitors": 7 },    { "date": "2026-05-20T00:00:00.000Z", "pageviews": 22, "visitors": 9 },    { "date": "2026-05-21T00:00:00.000Z", "pageviews": 15, "visitors": 5 }  ]}

Response fields

period

string

Resolved reporting period.

granularity

"hour" | "day"

Time bucket size used for the response.

data[].date

string

ISO timestamp for the bucket start.

data[].pageviews

number

Pageviews in the bucket.

data[].visitors

number

Unique visitors in the bucket.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/pages

Returns the top pages for the project ranked by pageviews, along with unique visitor counts per page.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 10.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/pages?period=7d&limit=5", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const pages = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/pages?period=7d&limit=5" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "7d",  "data": [    { "path": "/", "pageviews": 80, "visitors": 25 },    { "path": "/contact/", "pageviews": 14, "visitors": 6 },    { "path": "/work-folio/", "pageviews": 8, "visitors": 5 }  ]}

Response fields

period

string

Resolved reporting period.

data[].path

string

Tracked page path.

data[].pageviews

number

Pageviews for the path.

data[].visitors

number

Unique visitors for the path.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/referrers

Returns traffic sources ranked by pageviews. Direct traffic (no referrer) is returned as (direct).

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 10.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/referrers?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const referrers = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/referrers?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "data": [    { "referrer": "(direct)", "pageviews": 62, "visitors": 20 },    { "referrer": "https://l.instagram.com/", "pageviews": 19, "visitors": 18 },    { "referrer": "https://www.google.com/", "pageviews": 7, "visitors": 5 }  ]}

Response fields

period

string

Resolved reporting period.

data[].referrer

string

Referrer URL or (direct).

data[].pageviews

number

Pageviews from the referrer.

data[].visitors

number

Unique visitors from the referrer.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/countries

Returns visitor breakdown by country, ranked by pageviews. Includes ISO country codes.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 10.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/countries?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const countries = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/countries?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "data": [    { "country": "Morocco", "country_code": "MA", "pageviews": 114, "visitors": 27 },    { "country": "United States", "country_code": "US", "pageviews": 8, "visitors": 3 },    { "country": "United Kingdom", "country_code": "GB", "pageviews": 4, "visitors": 2 }  ]}

Response fields

period

string

Resolved reporting period.

data[].country

string

Country name.

data[].country_code

string

ISO 3166-1 alpha-2 country code.

data[].pageviews

number

Pageviews from the country.

data[].visitors

number

Unique visitors from the country.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/cities

Returns visitor breakdown by city, ranked by unique visitors. Only cities with known geo data are returned.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 10.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/cities?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const cities = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/cities?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "data": [    { "city": "Casablanca", "country": "Morocco", "country_code": "MA", "visitors": 14, "pageviews": 38 },    { "city": "Rabat",      "country": "Morocco", "country_code": "MA", "visitors": 8,  "pageviews": 21 },    { "city": "New York",   "country": "United States", "country_code": "US", "visitors": 3, "pageviews": 5 }  ]}

Response fields

period

string

Resolved reporting period.

data[].city

string

City name.

data[].country

string

Country name.

data[].country_code

string

ISO 3166-1 alpha-2 country code.

data[].visitors

number

Unique visitors from the city.

data[].pageviews

number

Pageviews from the city.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/devices

Returns visitor breakdown by device type, browser, and operating system — all in a single response.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/devices?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const devices = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/devices?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "devices": [    { "name": "Mobile", "visitors": 28 },    { "name": "Desktop", "visitors": 7 }  ],  "browsers": [    { "name": "Chrome", "visitors": 18 },    { "name": "Safari", "visitors": 12 },    { "name": "Firefox", "visitors": 5 }  ],  "os": [    { "name": "Android", "visitors": 16 },    { "name": "iOS", "visitors": 11 },    { "name": "Windows", "visitors": 5 }  ]}

Response fields

period

string

Resolved reporting period.

devices[].name

string

Device type such as Mobile, Desktop, Tablet, or Unknown.

devices[].visitors

number

Unique visitors for that device type.

browsers[].name

string

Browser name.

browsers[].visitors

number

Unique visitors for that browser.

os[].name

string

Operating system name.

os[].visitors

number

Unique visitors for that operating system.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/browsers

Returns visitor breakdown by browser, ranked by unique visitors.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 10.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/browsers?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const browsers = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/browsers?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "data": [    { "name": "Chrome",  "visitors": 18 },    { "name": "Safari",  "visitors": 12 },    { "name": "Firefox", "visitors": 5 }  ]}

Response fields

period

string

Resolved reporting period.

data[].name

string

Browser name.

data[].visitors

number

Unique visitors for that browser.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/os

Returns visitor breakdown by operating system, ranked by unique visitors.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 10.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/os?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const operatingSystems = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/os?period=30d" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "data": [    { "name": "Android", "visitors": 16 },    { "name": "iOS",     "visitors": 11 },    { "name": "Windows", "visitors": 5 }  ]}

Response fields

period

string

Resolved reporting period.

data[].name

string

Operating system name.

data[].visitors

number

Unique visitors for that operating system.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/events

Returns custom and transaction events ranked by count for the period, including summed tracker transaction amounts when a single currency is present. Works with an API key (ClickHouse-backed).

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max results to return. Maximum 100, default 20.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/events?period=30d&limit=20", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const events = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/events?period=30d&limit=20" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "period": "30d",  "data": [    { "name": "signup", "people": 42, "events": 48, "pct": 0.61, "amountCents": null, "currency": null, "transactions": 0 },    { "name": "purchase", "people": 12, "events": 15, "pct": 0.19, "amountCents": 149850, "currency": "USD", "transactions": 15 }  ]}

Response fields

period

string

Resolved reporting period.

data[].name

string

Event name from track() or transaction().

data[].people

number

Unique visitors who fired the event.

data[].events

number

Total event count (custom + transaction).

data[].pct

number

Share of all events in the result set (0–1).

data[].amountCents

number | null

Sum of transaction amounts in minor units. Null when none, or when multiple currencies were recorded for the name.

data[].currency

string | null

ISO 4217 currency when amountCents is set; null otherwise.

data[].transactions

number

How many of events are type=transaction.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/goals

Returns project goals with current stats for the period. Prefer a session Bearer token — API keys may receive an empty goals list because the underlying action is session-only.

Parameters

periodoptional

Page period: today, 7d, 30d, 6m, or 12m. Defaults to 30d.

string

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/goals?period=30d", {  headers: { Authorization: `Bearer ${SESSION_TOKEN}` },}) const { goals } = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/goals?period=30d" \  -H "Authorization: Bearer session_token"

Response

json
{  "period": "30d",  "goals": [    {      "id": "g1",      "name": "Signups",      "type": "event",      "value": "signup",      "target": 100,      "category": "conversion",      "direction": "up",      "format": "number",      "current": 42,      "conversionRate": 0.12    }  ]}

Response fields

period

string

Resolved reporting period.

goals[].id

string

Goal identifier.

goals[].name

string

Goal display name.

goals[].type

string

Goal type (event, pageview, traffic, engagement, revenue, …).

goals[].value

string

Matching value for the goal type (e.g. event name or path).

goals[].target

number | null

Optional target value.

goals[].category

string

Goal category such as conversion, traffic, engagement, or revenue.

goals[].current

number

Current metric value for the period.

goals[].conversionRate

number | null

Conversion rate for conversion goals; null otherwise.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

GET/api/v1/projects/{domain}/bots

Returns bot traffic totals, a time series, top bots, and top crawled pages. Prefer a session Bearer token — API keys may receive empty traffic because the underlying action is session-only.

Parameters

periodoptional

Page period: today, 7d, 30d, 6m, or 12m. Defaults to 7d.

string

filteroptional

Bot category filter: all (default), ai_answer, indexing, training, or other.

string

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/bots?period=7d&filter=all", {  headers: { Authorization: `Bearer ${SESSION_TOKEN}` },}) const bots = await res.json()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/bots?period=7d&filter=all" \  -H "Authorization: Bearer session_token"

Response

json
{  "period": "7d",  "filter": "all",  "data": {    "totals": { "all": 120, "verified": 95, "ai_answer": 40, "indexing": 50, "training": 20, "other": 10 },    "series": [      { "date": 1716163200000, "count": 18, "byBot": [{ "name": "Googlebot", "count": 12 }] }    ],    "topBots": [      { "slug": "googlebot", "name": "Googlebot", "category": "indexing", "count": 50, "verified": 48 }    ],    "topPages": [      { "path": "/", "count": 40 }    ]  }}

Response fields

period

string

Resolved reporting period.

filter

string

Applied bot category filter.

data.totals

object

Counts by category plus all and verified.

data.series

array

Time buckets with per-bot breakdowns.

data.topBots

array

Top bots by crawl count.

data.topPages

array

Most crawled paths.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

POST/api/v1/projects/{domain}/install/verify

Checks whether the tracker has started sending events for this project. Requires a write-scoped API key or session.

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/install/verify", {  method: "POST",  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const result = await res.json()

cURL

bash
curl -X POST "https://api.openrevenue.com/api/v1/projects/example.com/install/verify" \  -H "Authorization: Bearer openrevenue_your_key"

Response

json
{  "verified": true,  "installationSeenAt": "2026-05-01T12:00:00.000Z"}

Response fields

verified

boolean

True when install has been confirmed via timestamp or ClickHouse events.

installationSeenAt

string | null

ISO timestamp when install was first recorded, or null if verified only via events.

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

403
API key is read-only

The key does not include the write scope.

404
Project not found

No project with that domain exists for the authenticated user.

429
Too many requests

Rate limit exceeded.

GET/api/v1/projects/{domain}/export

Downloads analytics as a CSV file (Content-Type: text/csv). Sections include overview, pages, referrers, countries, browsers, and operating systems. Works with an API key.

Parameters

periodoptional

Time period. See Periods on Account API page. Defaults to 30d.

string

limitoptional

Max rows per section. Maximum 500, default 100.

integer

JavaScript

index.ts
const res = await fetch("https://api.openrevenue.com/api/v1/projects/example.com/export?period=30d", {  headers: { Authorization: `Bearer ${OPENREVENUE_API_KEY}` },}) const csv = await res.text()

cURL

bash
curl "https://api.openrevenue.com/api/v1/projects/example.com/export?period=30d" \  -H "Authorization: Bearer openrevenue_your_key" \  -o openrevenue-example.com-30d.csv

Response

json
# OpenRevenue export — example.com — period 30d# Generated 2026-05-25T10:00:00.000Z # Overviewmetric,valuevisitors,35pageviews,130sessions,48avg_duration_seconds,94 # Pagespath,pageviews,visitors/,80,25...

Response fields

Content-Type

text/csv

Response body is CSV, not JSON.

Content-Disposition

string

attachment; filename="openrevenue-{domain}-{period}.csv".

Errors

401
Invalid or missing API key

The Authorization header is missing or the Bearer token is invalid.

404
Project not found

No project with that domain exists for the authenticated user.

429
Too many requests

Rate limit exceeded.