Every report, over plain JSON
One key reads your traffic reports, goals and custom events, with the dashboard filters, and with the manage scope adds and verifies sites. Full history by default, real response shapes below, included on every plan. Prefer asking an AI instead of writing code? Use the MCP server.
Base URL https://analytics.devdome.com, HTTPS only, JSON in and out. Every sample on this page is a
real captured response, trimmed for length. The same table as a machine-readable
OpenAPI 3.0 document, generated from this page's source.
Authentication
Create a key under Account → API and send it as a Bearer token on every request. The key can read every site on the account - treat it like a password. Only a hash is stored, so it is shown exactly once; rotate or revoke it any time and the old key dies within minutes.
curl "https://analytics.devdome.com/api/v1/stats?site=example.com" \
-H "Authorization: Bearer ddk_your_key_here"
International domains are addressed in punycode, exactly as stored:
site=xn--mnchen-3ya.de for münchen.de.
First success in five minutes
- Create a key under Account → API (read-only is enough for reports) and copy it once.
- List what the key can see:
curl https://analytics.devdome.com/api/v1/sites -H "Authorization: Bearer ddk_..." - Ask for one site's last week:
curl "https://analytics.devdome.com/api/v1/stats?site=example.com&days=7" -H "Authorization: Bearer ddk_..."
Two rows come back,currentandprevious, so the change is yours to compute. - Narrow it like the dashboard does, for example only visits from Google: add
&filter_referrer=google.com. - Generate a typed client from the OpenAPI document:
npx openapi-typescript https://devdome.com/docs/api/openapi.json -o devdome-api.d.ts
A 401 means the key was mistyped or revoked; a 403 on POST /sites means the key is read-only. Everything else is in the error table at the end.
Code samples
The same first call in four languages. Each one reads the key from the environment, never from the source, and asks for one site's last seven days with the Google filter.
curl
curl "https://analytics.devdome.com/api/v1/stats?site=example.com&days=7" \
-H "Authorization: Bearer $DEVDOME_API_KEY"
# only visits that came from Google
curl "https://analytics.devdome.com/api/v1/stats?site=example.com&days=7&filter_referrer=google.com" \
-H "Authorization: Bearer $DEVDOME_API_KEY" JavaScript (fetch)
const BASE = "https://analytics.devdome.com";
const headers = { Authorization: `Bearer ${process.env.DEVDOME_API_KEY}` };
async function stats(site, days = 7, filters = {}) {
const q = new URLSearchParams({ site, days: String(days), ...filters });
const r = await fetch(`${BASE}/api/v1/stats?${q}`, { headers });
if (!r.ok) throw new Error(`DevDome ${r.status}: ${await r.text()}`);
return r.json(); // [current, previous]
}
const [current, previous] = await stats("example.com", 7, { filter_referrer: "google.com" });
console.log(current.visitors, "visitors this week,", previous.visitors, "the week before"); Python (requests)
import os, requests
BASE = "https://analytics.devdome.com"
HEADERS = {"Authorization": f"Bearer {os.environ['DEVDOME_API_KEY']}"}
def stats(site, days=7, **filters):
r = requests.get(f"{BASE}/api/v1/stats", params={"site": site, "days": days, **filters}, headers=HEADERS, timeout=15)
r.raise_for_status() # 401 = bad key, 429 = slow down (see the error table)
return r.json() # [current, previous]
current, previous = stats("example.com", days=7, filter_referrer="google.com")
print(current["visitors"], "visitors this week,", previous["visitors"], "the week before") PHP (WordPress)
<?php
// Inside a plugin or theme: WordPress's HTTP API, the key from wp-config.php (define('DEVDOME_API_KEY', '...')).
function devdome_stats( $site, $days = 7, $filters = array() ) {
$url = add_query_arg( array_merge( array( 'site' => $site, 'days' => $days ), $filters ), 'https://analytics.devdome.com/api/v1/stats' );
$resp = wp_remote_get( $url, array( 'timeout' => 15, 'headers' => array( 'Authorization' => 'Bearer ' . DEVDOME_API_KEY ) ) );
if ( is_wp_error( $resp ) || 200 !== wp_remote_retrieve_response_code( $resp ) ) {
return null; // the body holds {"error": "..."}; see the error table
}
return json_decode( wp_remote_retrieve_body( $resp ), true ); // [current, previous]
}
$rows = devdome_stats( 'example.com', 7, array( 'filter_referrer' => 'google.com' ) );
echo $rows[0]['visitors'] . ' visitors this week'; Time windows
Every traffic, audience, visitor and bot endpoint accepts days=N or
from=YYYY-MM-DD&to=YYYY-MM-DD (ISO timestamps work too); hourly and
realtime are fixed windows and health takes days only. No window parameter means the full
history your plan retains - the API never silently defaults to 30 days, and a malformed
days is a 400. The window that actually answered rides in the
x-dd-effective-window response header on the traffic, audience, visitor and bot
endpoints (health, incidents and alerts do not carry it): days=N; requested=N; cap=N;
plan=...; clamped=0|1, plus from=...; to=... when you asked by calendar.
hourly reports fixed=24h and realtime fixed=5m.
Account and sites
Who you are and what you track. Adding and verifying sites works exactly like the dashboard wizard.
GET/api/v1/account
Who am I: account id and plan.
{"account_id": "DD12345678", "plan": "pro"} GET/api/v1/sites
Every site on the account.
{"sites": [
{"domain": "example.com", "verified": true, "pending_verification": false, "category": null},
{"domain": "newsite.com", "verified": false, "pending_verification": true, "category": null}
]} verified = ownership proven. pending_verification = added but not verified yet; no data access until it is.
POST/api/v1/sites
Add a site. Creates a pending claim and returns the verification file to upload: verify_file_path (/.well-known/devdome-analytics.txt) and verify_content. The tracking snippet itself is in the dashboard and the WordPress plugin.
curl -X POST "https://analytics.devdome.com/api/v1/sites" \
-H "Authorization: Bearer ddk_..." \
-H "content-type: application/json" \
-d '{"domain": "newsite.com"}' POST/api/v1/sites/{domain}/verify
Verify ownership: passes when the live homepage carries your snippet, or a DNS TXT record devdome-verify=DD... exists.
DELETE/api/v1/sites/{domain}
Remove the site from the account. A site that still has analytics data answers 409 until you add ?purge=1, which removes the site and deletes its data for good.
?purge
Traffic
The headline numbers and the per-page detail. Every count comes with its bot twin, so human numbers are never inflated. Every windowed report takes the dashboard filters as filter_page, filter_referrer, filter_browser, filter_os, filter_device, filter_country, filter_campaign (source|medium|campaign), filter_event and filter_goal (a goal id); each narrows the report to the visits that match, inside the same window. countries, regions and cities ignore the page, referrer, campaign, event and goal filters.
GET/api/v1/stats
Headline KPIs for the window plus the previous window (period "current" / "previous") so you can compute changes.
?site, days | from+to
[
{"period": "current", "visitors": 2450, "new_visitors": 1830,
"returning_visitors": 620, "bots": 1892, "pageviews": 6120,
"bot_pageviews": 3011, "clicks": 214, "bot_clicks": 12,
"sessions": 3105, "bounces": 1420, "session_seconds": 512400,
"dur_sessions": 3105, "visits": 3105},
{"period": "previous", "...": "same fields, the window before"}
] How the numbers are counted. visits = sessions with the 30-minute gap rule. session_seconds / visits = average visit duration (every visit counts, a bounce as 0 seconds; dur_sessions, the visits with a measured dwell, stays in the answer for older integrations). bounces = one-page visits without an outbound click; bounces / visits = bounce rate. visitors = distinct identities that loaded a page in the window; people who only passed through a tracked redirect link and never loaded a page are reported apart as hop_only_visitors. Counting changes on 19 October 2026: a click or a redirect-hop landing no longer starts a visit (visits and bounce rate drop on redirect-heavy sites), a one-page visit with an outbound click is no longer a bounce, the average runs over every visit, and visitors counts page loaders only. new_visitors = identities seen for the first time in the window; it is only meaningful when the site recognises returning visitors. Cookieless tracking rotates the visitor id every day, so every return visit looks new. Two switches decide this and must agree: the tracker (hosted snippet: data-cookieless="true" on the script tag; WordPress plugin: Track Returning Visitors off) and the dashboard (Website Settings > Cookieless tracking). With the dashboard switch on, new_visitors is null and returning_visitors is 0: do not report them. If new_visitors is almost equal to visitors, the tracker runs in cookieless mode but the dashboard switch is off: turn Cookieless tracking on for that site, or turn returning-visitor tracking on in the tracker, so the two agree.
GET/api/v1/timeseries
One row per day, zero-filled, bucketed in the site timezone.
?site, days | from+to
[
{"day": "2026-08-19", "visitors": 312, "visits": 398, "bots": 244,
"pageviews": 801, "clicks": 31, "ctr": 7.8, "ppv": 2.01,
"sessions": 398, "bounces": 171, "new_visitors": 231},
{"day": "2026-08-20", "...": "one zero-filled row per day"}
] ctr = human clicks / visits in percent, the same formula as the dashboard CTR tile. ppv = pageviews / visits. hop_only_visitors = identities that only passed through a redirect link that day and never loaded a page (not in visitors).
GET/api/v1/hourly
The last 24 hours by hour (UTC timestamps).
?site
[
{"hour": "2026-08-21T19:00:00.000Z", "visitors": 14, "bots": 6,
"pageviews": 31, "clicks": 2, "visits": 17},
{"...": "24 rows"}
] Fixed window: the header says fixed=24h.
GET/api/v1/pages
Per-page traffic with page health.
?site, days | from+to, limit
[
{"page_path": "/pricing", "traffic": 302, "visitors": 287, "bots": 44,
"clicks": 21, "status": 200,
"checked_at": "2026-08-22T18:20:29.149+00:00",
"_total": 214, "_t404": 3}
] status / checked_at come from the page health prober (404 detection). With limit=N, row 0 carries _total (all pages) and _t404 (broken count).
GET/api/v1/referrers
Traffic sources, one row per referrer.
?site, days | from+to
[
{"referrer": "google.com", "visits": 1211, "clicks": 84},
{"referrer": "direct", "visits": 903, "clicks": 61},
{"referrer": "reddit.com", "visits": 88, "clicks": 9}
] visits = visits whose first pageview arrived from that source (30-minute gap rule); the rows add up to the Visits KPI. clicks = outbound clicks made during those visits.
GET/api/v1/redirects
Redirect slugs served, with clicks through them.
?site, days | from+to
GET/api/v1/keywords
Search keywords, where engines disclose them.
?site, days | from+to
GET/api/v1/products
Amazon product clicks (Amazon Importer sites).
?site, days | from+to
GET/api/v1/campaigns
UTM campaigns: one row per utm_source / utm_medium / utm_campaign on the links visitors landed from, with visits, people and bot landings. Tags are stored from 10 Oct 2026 on.
?site, days | from+to
GET/api/v1/goals
The saved goals of the site (Website Settings > Goals) with the human and bot visits that completed each one in the window. Each row carries the goal id used by filter_goal.
?site, days | from+to
GET/api/v1/events
Custom events the site sends, one row per event name with counts for the window. Names feed filter_event.
?site, days | from+to
Audience
Where visitors are and what they browse with. Rows in these tables use short keys, decoded below.
GET/api/v1/countries
Traffic by country (ISO 3166-1 alpha-2).
?site, days | from+to
[
{"country": "US", "visitors": 5, "bots": 2, "clicks": 0,
"pageviews": 5, "visits": 5},
{"country": "IE", "visitors": 2, "bots": 0, "clicks": 0,
"pageviews": 2, "visits": 2}
] GET/api/v1/regions
Regions inside one country.
?site, country, days | from+to
GET/api/v1/cities
Cities inside one region.
?site, country, region, days | from+to
GET/api/v1/devices
Device split with sub-breakdowns.
?site, days | from+to
{"rows": [
{"k": "desktop", "t": 9, "b": 2, "c": 0, "cb": 0, "uv": 9, "pv": 9}
],
"subs": [
{"k": "desktop", "dim": "browser", "skey": "chrome", "t": 9, "c": 0},
{"k": "desktop", "dim": "country", "skey": "US", "t": 5, "c": 0}
]} Short keys: k = dimension value, t = visits, b = bot visits, c = clicks, cb = bot clicks, uv = unique visitors, pv = pageviews. subs = the same value split by a second dimension.
GET/api/v1/browsers
Browser split. Same shape as devices.
?site, days | from+to
GET/api/v1/os
Operating system split. Same shape as devices.
?site, days | from+to
GET/api/v1/dates
Per-date table. Same shape as devices, keyed by date.
?site, days | from+to
Visitors and realtime
Individual anonymous visits with their full paths, and who is on the site right now.
GET/api/v1/visitors
Recent visits, each with its step-by-step path.
?site, days | from+to, limit, before
[
{"visitor_id": "09d307d8...", "country": "US", "browser": "chrome",
"os": "windows", "device": "desktop", "is_bot": false,
"entry": "direct", "last_seen": "2026-08-22T08:59:27.640Z",
"steps": [
{"t": "2026-08-22T08:59:27.640Z", "type": "pageview",
"page": "/pricing", "secs": 5}
]}
] visitor_id is a daily-rotating anonymous hash, never a person. steps carry pageviews and outbound clicks with per-page dwell seconds. Newest first; the window holds at most the plan row cap (500 on Free, 5,000 on paid plans) and row 0 carries that count as _total. Page with limit plus before = the last_seen of the last row you got; a page shorter than limit is the end. Narrow the window with from+to to reach visits past the cap.
GET/api/v1/paths
The visitors who entered on one page, each with their step-by-step path.
?site, page, days | from+to
page is required (the entry page path, e.g. /pricing); without it the call is a 400.
GET/api/v1/realtime
Visitors active in the last 5 minutes with their current page.
?site
Fixed window: the header says fixed=5m.
Bots
The report nobody else gives you over an API: every detected bot with the receipt for WHY it was flagged.
GET/api/v1/bots
Every detected bot: user agent, reason, hits, IPs, networks, pages.
?site, days | from+to, limit
[
{"user_agent": "Mozilla/5.0 (X11; Linux x86_64) ... Chrome/124.0",
"reason": "datacenter ASN (Amazon Data Services), automation (BotD:headless_chrome)",
"hits": 2, "ips": 2, "countries": ["US"],
"asns": ["Amazon Data Services Northern Virginia"],
"pages": ["/report/example"],
"last_seen": "2026-08-22T08:59:06.607Z"}
] limit takes 1 to 1000. No limit returns up to the plan cap (500 rows Free, 5000 paid).
GET/api/v1/bot-threats
Detection-category totals for the window.
?site, days | from+to
[
{"bots": 2, "ua_bots": 0, "datacenter": 2, "scanner": 0,
"automation": 2, "no_profile": 0, "session_bot": 0, "fleet": 0}
] Site health
The uptime and health monitoring that rides on the same key.
GET/api/v1/health
Full health report: uptime, response times, TLS, DNS, page checks.
?site, days
{"domain": "example.com",
"meta": {"monitor_state": "up", "cadence_s": 3600, "plan": "pro",
"effective_days": 30, "data_state": "ready",
"coverage_24h": 0.98, "latency_metric": "ttfb_ms"},
"sections": {"last_check": true, "incidents": true, "audit": true}} No days = the full history your plan retains; larger values are clamped to the plan.
GET/api/v1/incidents
Downtime incidents, newest first.
?site, limit, before
{"incidents": [], "limit": 25, "has_more": false} limit is 25 by default, 100 at most. When has_more is true, pass the started_at of the last row as before to page further back.
GET/api/v1/alerts
Alert history for the site.
?site
Export
Everything, raw.
GET/api/v1/export
Full CSV export of the raw analytics for the window. Returns text/csv, not JSON.
?site, days | from+to
One response, no paging: with no window it streams the whole history your plan retains, which can be tens of megabytes. Export month by month with from+to for anything large.
Rate limits and errors
Every error is {"error": "human readable message"} with a matching status:
- 400 - missing or malformed parameter; the message names it. days must be a whole number from 1 up; days=0 or days=abc is a 400, never a silent 30-day answer. Above the ceiling (1095) it clamps and the header says clamped=1.
- 401 - missing or invalid API key.
- 403 - the key is read-only: creating, verifying or removing a site needs a key with the "read and manage sites" scope (Account, API access). Reads work with every key.
- 403 - the site does not belong to this account.
- 404 - unknown endpoint.
- 423 - the account is over its plan limit and dashboards are locked.
- 429 - rate limited (60 requests/minute per key, plus 60 requests/minute per IP address for calls that need a fresh key lookup); comes with a retry-after: 60 header.
On the roadmap
Write endpoints for site settings, share links and the bot protection policy are planned as phase 2. Tell us what you need first via the contact page.
Get your key and make the first call
The API is included on every plan, the free one too. Create the key, paste the curl above, done.