API Documentation

Access your visitor intelligence data programmatically. Build integrations, create custom reports, and power your analytics workflow.

ⓘ

Base URL: https://www.identity-js.com/api/v1
All endpoints are read-only (GET) and return JSON. The API is versioned — v1 is the current stable release.

Authentication

All API requests require a Secret API Key (sk_live_ prefix) passed as a Bearer token. Generate one in your Dashboard under the API button.

⚠

Keep your secret key private. Never expose it in client-side code, public repos, or browser-accessible files. It grants full read access to your project data. If compromised, regenerate it immediately from the dashboard.

# Include in every request
curl -H "Authorization: Bearer sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345" \
  https://www.identity-js.com/api/v1/visitors

Your public key (pk_live_) is for the tracker script only and cannot be used for API access.

Rate Limits

The API allows 60 requests per minute per secret key. Exceeding this returns a 429 status with a JSON error body.

{
  "error": {
    "status": 429,
    "message": "Rate limit exceeded. Max 60 requests per minute.",
    "code": "rate_limited"
  }
}

Pagination

List endpoints return paginated results. Control pagination with these query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-based)
`limit`	integer	50	Results per page (max 100)

Paginated responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "total": 1847,
    "page": 1,
    "limit": 50,
    "total_pages": 37,
    "has_next": true,
    "has_prev": false
  }
}

Date Filtering

Most endpoints accept date range filters. If omitted, defaults to the last 30 days.

Parameter	Format	Example
`start_date`	YYYY-MM-DD	`2025-01-01`
`end_date`	YYYY-MM-DD	`2025-01-31`

# Get visitors from January 2025
GET /api/v1/visitors?start_date=2025-01-01&end_date=2025-01-31

Error Handling

Errors return a consistent JSON structure with an HTTP status code:

Status	Code	Description
400	`invalid_date`	Invalid date format in query parameters
401	`unauthorized`	Missing or invalid API key
404	`not_found`	Resource or endpoint not found
429	`rate_limited`	Too many requests — slow down

Visitors

GET /api/v1/visitors List all visitors with pagination and filters ▶

Returns a paginated list of visitors for your project. Bots (bot_score > 40) are automatically excluded.

Query Parameters

Param	Type		Description
`page`	integer	optional	Page number (default: 1)
`limit`	integer	optional	Results per page (default: 50, max: 100)
`start_date`	string	optional	Filter from date (YYYY-MM-DD)
`end_date`	string	optional	Filter to date (YYYY-MM-DD)
`browser`	string	optional	Filter by browser name (e.g. "Chrome")
`os`	string	optional	Filter by operating system (e.g. "Windows")
`country`	string	optional	Filter by country code (e.g. "US", "RS")
`search`	string	optional	Search across visitor ID, browser, OS, location, IP

Response

{
  "data": [
    {
      "visitor_id": "v_a1b2c3d4e5f6",
      "fingerprint_hash": "8f14e45fceea167a5a36...",
      "first_seen_at": 1719216000000,
      "last_seen_at": 1719302400000,
      "visit_count": 12,
      "browser_name": "Chrome",
      "browser_version": "126.0.0.0",
      "os": "Windows",
      "mobile": 0,
      "screen_width": 1920,
      "screen_height": 1080,
      "timezone": "Europe/Belgrade",
      "language": "sr",
      "geo_country": "Serbia",
      "geo_country_code": "RS",
      "geo_city": "Belgrade",
      "bot_score": 5,
      "ad_block": 0
    }
  ],
  "pagination": { "total": 342, "page": 1, "limit": 50, "total_pages": 7, "has_next": true, "has_prev": false }
}

Try it

Visitor Detail

GET /api/v1/visitors/:visitor_id Get full visitor profile with sessions and events ▶

Returns a single visitor's full profile including their session history, recent events, and linked aliases.

Path Parameters

Param	Type		Description
`visitor_id`	string	required	The visitor's unique identifier

Response

{
  "data": {
    "visitor_id": "v_a1b2c3d4e5f6",
    "first_seen_at": 1719216000000,
    "last_seen_at": 1719302400000,
    "visit_count": 12,
    "browser_name": "Chrome",
    "os": "Windows",
    "geo_country": "Serbia",
    "geo_city": "Belgrade",
    "aliases": [],
    "sessions": [
      {
        "session_id": "ses_xyz...",
        "url": "/pricing",
        "started_at": 1719302400000,
        "duration_ms": 145200
      }
    ],
    "events": [
      {
        "id": 5821,
        "name": "page_view",
        "data": { "url": "/" },
        "created_at": 1719302400000
      }
    ]
  }
}

Sessions

GET /api/v1/sessions List sessions with pagination and filters ▶

Returns a paginated list of browsing sessions.

Query Parameters

Param	Type		Description
`page`	integer	optional	Page number
`limit`	integer	optional	Results per page (max 100)
`start_date`	string	optional	YYYY-MM-DD
`end_date`	string	optional	YYYY-MM-DD
`visitor_id`	string	optional	Filter by visitor
`url`	string	optional	Filter by URL (partial match)

Response

{
  "data": [
    {
      "session_id": "ses_abc123",
      "visitor_id": "v_a1b2c3d4e5f6",
      "url": "/",
      "referrer": "https://google.com",
      "utm_source": "google",
      "started_at": 1719302400000,
      "ended_at": 1719302545000,
      "duration_ms": 145000,
      "click_count": 8,
      "max_scroll_depth": 87,
      "browser_name": "Chrome",
      "os": "Windows",
      "geo_country_code": "RS",
      "geo_city": "Belgrade"
    }
  ],
  "pagination": { ... }
}

Session Detail

GET /api/v1/sessions/:session_id Get full session replay with all events ▶

Returns a single session with its full event timeline (up to 500 events). Useful for session replay and debugging.

Path Parameters

Param	Type		Description
`session_id`	string	required	The session identifier

Response includes all session metadata plus an `events` array with every tracked event in chronological order.

Events

GET /api/v1/events List events with filters ▶

Returns a paginated list of all tracked events across sessions.

Query Parameters

Param	Type		Description
`page`	integer	optional	Page number
`limit`	integer	optional	Results per page (max 100)
`start_date`	string	optional	YYYY-MM-DD
`end_date`	string	optional	YYYY-MM-DD
`type`	string	optional	Filter by event type (e.g. "rage_click", "page_view")
`visitor_id`	string	optional	Filter by visitor
`session_id`	string	optional	Filter by session

Event Types

Common event types tracked by the identity-js tracker:

page_view — Page navigation
rage_click — Repeated rapid clicks (frustration signal)
dead_click — Click on non-interactive element
phantom_click — Click on element that disappeared
js_exception — Uncaught JavaScript error
promise_rejection — Unhandled promise rejection
console_error — Console error message
console_warning — Console warning message
form_abandon — User started filling a form but left
frustration_score — Computed frustration score for a session
reading_behavior — Reading engagement metrics
seo_diagnostics — SEO issues detected on the page

Event Types

GET /api/v1/events/types Get event type counts ▶

Returns a breakdown of how many events of each type were recorded in the date range.

Response

{
  "data": [
    { "name": "page_view", "count": 12847 },
    { "name": "dead_click", "count": 234 },
    { "name": "rage_click", "count": 89 },
    { "name": "js_exception", "count": 45 }
  ]
}

Stats

GET /api/v1/stats Aggregate visitor and session stats ▶

Returns high-level aggregate statistics — total visitors, sessions, page views, bounce rate, average session duration, and more. Great for dashboards and status pages.

Query Parameters

Param	Type		Description
`start_date`	string	optional	YYYY-MM-DD
`end_date`	string	optional	YYYY-MM-DD

Top Pages

GET /api/v1/stats/pages Most visited pages ▶

Returns the most visited pages and the average pages per session.

Response

{
  "data": {
    "top_pages": [
      { "url": "/", "views": 8421, "unique_visitors": 3201 },
      { "url": "/pricing", "views": 2103, "unique_visitors": 1847 }
    ],
    "avg_pages_per_session": 3.2
  }
}

Live Visitors

GET /api/v1/live Currently active visitors ▶

Returns visitors currently active on your site (heartbeat within the last N minutes).

Query Parameters

Param	Type		Description
`threshold_minutes`	integer	optional	Consider active within last N minutes (default: 5)

Response

{
  "data": [
    {
      "visitor_id": "v_xyz123",
      "current_page": "/pricing",
      "browser_name": "Firefox",
      "geo_country": "Germany",
      "geo_city": "Berlin"
    }
  ],
  "count": 1
}

Frustration Scores

GET /api/v1/insights/frustration Visitor frustration scores ▶

Returns frustration scores computed from rage clicks, dead clicks, errors, form abandons, and rapid navigation. Higher scores indicate more frustrated users.

Response

{
  "data": {
    "scores": [
      {
        "visitor_id": "v_abc",
        "score": 78,
        "rage_clicks": 3,
        "dead_clicks": 5,
        "errors": 2,
        "form_abandons": 1
      }
    ],
    "average": { "avg_score": 23.4, "visitor_count": 156 }
  }
}

Errors & Warnings

GET /api/v1/insights/errors Top JavaScript errors and console warnings ▶

Returns the most frequent JavaScript errors and console warnings, grouped by message.

Click Issues

GET /api/v1/insights/clicks Rage clicks, dead clicks, phantom clicks ▶

Returns the top elements receiving problematic clicks — rage clicks (repeated fast clicks), dead clicks (non-interactive targets), and phantom clicks (element disappeared).

SEO Diagnostics

GET /api/v1/insights/seo SEO issues detected per page ▶

Returns SEO diagnostics collected by the tracker — missing meta tags, heading structure issues, image alt text, and more.

User Journeys

GET /api/v1/insights/journeys Page-to-page navigation transitions ▶

Returns the most common page transitions — which page visitors came from and where they went next. Useful for understanding navigation flows and finding drop-off points.

Reading Behavior

GET /api/v1/insights/reading Scroll depth and reading engagement per page ▶

Returns reading behavior metrics per page — scroll depth, active time, scroll velocity, and attention percentage.

Form Analytics

GET /api/v1/insights/forms Form abandonment and input hesitation ▶

Returns form abandonment hotspots and input fields where users hesitate (long pause before typing). Useful for optimizing conversion funnels.

Acquisition

GET /api/v1/acquisition Traffic sources, referrers, UTM campaigns ▶

Returns traffic acquisition data — top referrers, UTM parameters breakdown, and marketing channels. Essential for understanding where your visitors come from.

Web Metrics

GET /api/v1/metrics Core web vitals, bounce rate, session duration ▶

Returns performance metrics including Web Vitals (LCP, FID, CLS), average session duration, bounce rate, and top pages.

Code Examples

cURL

curl -s -H "Authorization: Bearer $IDENTITY_API_KEY" \
  "https://www.identity-js.com/api/v1/stats?start_date=2025-06-01" | jq .

JavaScript (Node.js)

const API_KEY = process.env.IDENTITY_API_KEY;

async function getVisitors(page = 1) {
  const res = await fetch(
    `https://www.identity-js.com/api/v1/visitors?page=${page}&limit=100`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

// Get all visitors from this week
const { data, pagination } = await getVisitors();
console.log(`Found ${pagination.total} visitors`);

Python

import requests, os

API_KEY = os.environ["IDENTITY_API_KEY"]
BASE    = "https://www.identity-js.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Get frustration scores for the last 7 days
r = requests.get(f"{BASE}/insights/frustration?start_date=2025-06-18", headers=headers)
data = r.json()

for entry in data["data"]["scores"]:
    if entry["score"] > 50:
        print(f"Frustrated: {entry['visitor_id']} (score: {entry['score']})")

Ready to build?

Generate your API key in the dashboard and start integrating.

Open Dashboard →

API Documentation

Authentication

Rate Limits

Pagination

Date Filtering

Error Handling

Visitors

Query Parameters

Response

Visitor Detail

Path Parameters

Response

Sessions

Query Parameters

Response

Session Detail

Path Parameters

Response includes all session metadata plus an events array with every tracked event in chronological order.

Events

Query Parameters

Event Types

Event Types

Response

Stats

Query Parameters

Top Pages

Response

Live Visitors

Query Parameters

Response

Frustration Scores

Response

Errors & Warnings

Click Issues

SEO Diagnostics

User Journeys

Reading Behavior

Form Analytics

Acquisition

Web Metrics

Code Examples

cURL

JavaScript (Node.js)

Python

Ready to build?

Response includes all session metadata plus an `events` array with every tracked event in chronological order.