Access your Session Story analytics data programmatically. The same API that powers the dashboard is available for direct use.
All API requests require a Bearer token. You can find your API key on any site's settings page in the dashboard.
Include it in the Authorization header:
Authorization: Bearer sk_your_api_key_hereAll authenticated endpoints return 401 Unauthorized if the token is missing or invalid, and 403 Forbidden if the resource doesn't belong to your account.
https://www.sessionstory.io/apiReturns all sites belonging to the authenticated user, including visitor/session/event counts and a 7-day sparkline.
GET /api/sites[
{
"id": "abc123",
"name": "My Site",
"domain": "example.com",
"tracking_id": "site_xxxxxxxxxxxxxxxx",
"visitors_count": 1200,
"sessions_count": 3400,
"events_count": 15000,
"sparkline": [12, 18, 25, 30, 22, 19, 28]
}
]GET /api/sites/{site_id}{
"id": "abc123",
"name": "My Site",
"domain": "example.com",
"tracking_id": "site_xxxxxxxxxxxxxxxx",
"visitors_count": 1200,
"sessions_count": 3400,
"events_count": 15000
}POST /api/sites{
"name": "My New Site",
"domain": "newsite.com"
}| Field | Type | Description |
|---|---|---|
| name | string | Required. Display name for the site. |
| domain | string | Required. Domain of the site. |
Returns the main analytics overview for a site — sessions over time, bounce rate, average session duration, referrers, top pages, top events, countries, and devices.
GET /api/sites/{site_id}/analytics/dashboard| Param | Type | Description |
|---|---|---|
| from | datetime | Optional. Start of date range (ISO 8601). |
| to | datetime | Optional. End of date range. Defaults to now. |
| Field | Description |
|---|---|
| sessions_over_time | Array of {period, count} objects. |
| granularity | "hour" or "day", based on date range. |
| total_sessions | Total session count in the range. |
| bounce_rate | Percentage of sessions with ≤ 1 pageview. |
| avg_session_duration | Average session duration in seconds. |
| referrers | Top 10 traffic sources with counts. |
| top_pages | Top 10 pages by pageview count. |
| top_events | Top 10 custom events (deduplicated per session). |
| countries | Sessions by country code. |
| devices | Sessions by device type (Phone, Tablet, Desktop). |
Returns revenue analytics if revenue tracking is configured for the site.
GET /api/sites/{site_id}/analytics/revenue| Param | Type | Description |
|---|---|---|
| from | datetime | Optional. Start of date range. |
| to | datetime | Optional. End of date range. |
| Field | Description |
|---|---|
| configured | Boolean. False if revenue tracking is not set up. |
| summary | {total_revenue, total_transactions, avg_order_value} |
| revenue_over_time | Array of {period, revenue, transactions}. |
| by_source | Revenue breakdown by traffic source. |
| by_campaign | Revenue breakdown by source and campaign. |
Analyzes visitor behavior quality by traffic source and campaign. Categorizes sessions into behavior buckets: bouncer, skimmer, hesitator, or engaged.
GET /api/sites/{site_id}/analytics/friction| Param | Type | Description |
|---|---|---|
| from | datetime | Optional. Start of date range. |
| to | datetime | Optional. End of date range. |
Returns a sources array, each with key, total, buckets, bucket_pct, and nested campaigns array with the same structure.
Returns scroll depth distribution (25%, 50%, 75%, 100%) per page.
GET /api/sites/{site_id}/analytics/scroll-depth| Param | Type | Description |
|---|---|---|
| url | string | Optional. Filter to a specific page URL. |
| limit | integer | Optional. Max pages to return (default 20, max 100). |
Shows how many sessions reach each scroll depth milestone on a given page.
GET /api/sites/{site_id}/analytics/engagement-funnel| Param | Type | Description |
|---|---|---|
| url | string | Optional. Filter to a specific page URL. |
Shows what percentage of sessions from each source/campaign reached a specific page or triggered a specific event.
GET /api/sites/{site_id}/analytics/reach| Param | Type | Description |
|---|---|---|
| metric | string | Required. "page" or "event". |
| value | string | Required. The page path or event type to measure reach for. |
| from | datetime | Optional. Start of date range. |
| to | datetime | Optional. End of date range. |
Lists all custom event types tracked on the site with their counts.
GET /api/sites/{site_id}/analytics/custom-event-types| Param | Type | Description |
|---|---|---|
| from | datetime | Optional. Start of date range. |
| to | datetime | Optional. End of date range. |
Builds a conversion funnel from a sequence of custom event types. Shows how many sessions progress through each step.
GET /api/sites/{site_id}/analytics/custom-event-funnel| Param | Type | Description |
|---|---|---|
| steps[] | array | Required. 2-10 event type names defining the funnel steps. |
| from | datetime | Optional. Start of date range. |
| to | datetime | Optional. End of date range. |
GET /api/sites/{site_id}/analytics/custom-event-funnel?steps[]=signup_start&steps[]=signup_complete&steps[]=first_purchaseReturns the unique data property keys found in events of a given type. Useful for discovering what custom data is being tracked.
GET /api/sites/{site_id}/analytics/event-data-keys| Param | Type | Description |
|---|---|---|
| type | string | Required. The event type to inspect. |
Returns paginated visitors for a site, ordered by most recently seen.
GET /api/sites/{site_id}/visitors| Param | Type | Description |
|---|---|---|
| page | integer | Optional. Page number (50 visitors per page). |
Returns all sessions for a specific visitor.
GET /api/visitors/{visitor_id}/sessionsReturns all events in a specific session, ordered chronologically.
GET /api/visitors/{visitor_id}/sessions/{session_id}/events