API Reference
Visitors & Realtime
Visitor list, live visitor count, keywords, and attribution quality
Visitors & Realtime
Four endpoints for visitor data, realtime presence, search keywords, and attribution quality metrics.
Visitor List
GET /api/v1/visitorsPaginated list of all visitors (identified and anonymous). Returns PII fields like name and email.
Scope: visitors:read (must be explicitly granted)
PII access required
This endpoint returns personally identifiable information (name, email). Your API key must have the visitors:read scope explicitly granted. Keys with only analytics:read will receive a 403 Forbidden response.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | string | Yes | Start date (YYYY-MM-DD) |
date_to | string | Yes | End date (YYYY-MM-DD) |
search | string | No | Search by name or email |
limit | number | No | Results per page (default 10, max 100) |
cursor_time | string | No | Pagination cursor (ISO timestamp) |
cursor_id | string | No | Pagination cursor ID |
Request
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/visitors?date_from=2026-03-01&date_to=2026-03-25&limit=5"const response = await fetch(
"https://www.atribu.app/api/v1/visitors?date_from=2026-03-01&date_to=2026-03-25&limit=5",
{
headers: {
Authorization: "Bearer atb_live_YOUR_KEY",
},
}
);
const data = await response.json();import requests
resp = requests.get(
"https://www.atribu.app/api/v1/visitors",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
params={
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"limit": 5,
},
)
data = resp.json()Response
{
"data": [
{
"visitor_id": "uuid",
"customer_profile_id": "uuid",
"name": "John Doe",
"email": "[email protected]",
"country": "US",
"device": "desktop",
"browser": "Chrome",
"os": "macOS",
"channel": "Organic Search",
"source": "google",
"total_revenue": 450.00,
"last_seen_at": "2026-03-25T08:30:00Z",
"session_count": 5,
"total_pageviews": 18,
"touch_channels": ["Organic Search", "Direct", "Paid Social"]
}
],
"pagination": {
"has_next": true,
"cursor": "2026-03-25T08:30:00Z|uuid"
},
"meta": {
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"profile_id": "uuid"
}
}Response fields
| Field | Type | Description |
|---|---|---|
visitor_id | string | Unique visitor identifier (anonymous_id) |
customer_profile_id | string | null | Linked customer profile (null for anonymous visitors) |
name | string | Display name or deterministic anonymous name (e.g. "Teal Falcon") |
email | string | null | Email address if identified |
country | string | Two-letter country code |
device | string | Device type: desktop, mobile, tablet |
browser | string | Browser name |
os | string | Operating system |
channel | string | Classified traffic channel (see Channels) |
source | string | Traffic source |
total_revenue | number | Total attributed cash revenue |
last_seen_at | string | ISO timestamp of last activity |
session_count | number | Total sessions in the date range |
total_pageviews | number | Total page views in the date range |
touch_channels | string[] | All channels this visitor has interacted through |
Realtime
GET /api/v1/realtimeReturns the number of visitors currently on your site (active in the last 5 minutes).
Scope: realtime:read
No date parameters
This endpoint returns a live snapshot. No date_from or date_to parameters are needed.
Request
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/realtime"const response = await fetch(
"https://www.atribu.app/api/v1/realtime",
{
headers: {
Authorization: "Bearer atb_live_YOUR_KEY",
},
}
);
const data = await response.json();import requests
resp = requests.get(
"https://www.atribu.app/api/v1/realtime",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
)
data = resp.json()Response
{
"data": {
"visitors_online": 24
},
"meta": {
"profile_id": "uuid"
}
}Keywords
GET /api/v1/keywordsReturns Google Search Console keyword performance data. Requires an active GSC integration.
Scope: analytics:read
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | string | Yes | Start date (YYYY-MM-DD) |
date_to | string | Yes | End date (YYYY-MM-DD) |
limit | number | No | Max results (default 50, max 100) |
Request
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/keywords?date_from=2026-03-01&date_to=2026-03-25&limit=10"const response = await fetch(
"https://www.atribu.app/api/v1/keywords?date_from=2026-03-01&date_to=2026-03-25&limit=10",
{
headers: {
Authorization: "Bearer atb_live_YOUR_KEY",
},
}
);
const data = await response.json();import requests
resp = requests.get(
"https://www.atribu.app/api/v1/keywords",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
params={
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"limit": 10,
},
)
data = resp.json()Response
{
"data": [
{
"keyword": "marketing attribution tool",
"impressions": 2400,
"clicks": 180,
"ctr": 7.5,
"avg_position": 4.2
},
{
"keyword": "roas calculator",
"impressions": 1800,
"clicks": 95,
"ctr": 5.3,
"avg_position": 6.8
}
],
"meta": {
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"profile_id": "uuid"
}
}Response fields
| Field | Type | Description |
|---|---|---|
keyword | string | Search query term |
impressions | number | Times your site appeared in search results |
clicks | number | Times users clicked through to your site |
ctr | number | Click-through rate (clicks / impressions x 100) |
avg_position | number | Average ranking position in search results |
Quality
GET /api/v1/qualityReturns attribution data quality metrics -- how well your tracking captures marketing source data.
Scope: analytics:read
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | string | Yes | Start date (YYYY-MM-DD) |
date_to | string | Yes | End date (YYYY-MM-DD) |
Request
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/quality?date_from=2026-03-01&date_to=2026-03-25"const response = await fetch(
"https://www.atribu.app/api/v1/quality?date_from=2026-03-01&date_to=2026-03-25",
{
headers: {
Authorization: "Bearer atb_live_YOUR_KEY",
},
}
);
const data = await response.json();import requests
resp = requests.get(
"https://www.atribu.app/api/v1/quality",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
params={
"date_from": "2026-03-01",
"date_to": "2026-03-25",
},
)
data = resp.json()Response
{
"data": {
"total_events": 1450,
"with_full_utms": 890,
"with_fbclid_only": 320,
"with_no_tracking": 240,
"coverage_percent": 83.45
},
"meta": {
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"profile_id": "uuid"
}
}Response fields
| Field | Type | Description |
|---|---|---|
total_events | number | Total tracked events in the period |
with_full_utms | number | Events with complete UTM parameters |
with_fbclid_only | number | Events with only a click ID (fbclid/gclid) but no UTMs |
with_no_tracking | number | Events with no marketing source data at all |
coverage_percent | number | Percentage of events that have at least some attribution data |
Improving coverage
A low coverage_percent usually means UTM parameters are missing from your ad URLs. Ensure all campaigns include utm_source, utm_medium, and utm_campaign parameters. Click IDs (fbclid, gclid) are added automatically by ad platforms.