GET /v2/analytics/events
Bearer auth

Returns paginated raw engagement events (views and clicks) for the authenticated organization, filtered by date range and optional storyId / versionId / userEmail.

Plan

This endpoint is available on the Team plan only.

Date Range

Both dateFrom and dateTo are required ISO 8601 strings. The dateTo boundary is inclusive (events on the supplied day are returned). The maximum range is 92 days (3 months).

Pagination

Results are paginated with a fixed page size of 1000. Pages are 1-indexed. Use the pagination.hasMore flag to determine whether to request the next page.

Filtering by user

Pass userEmail to restrict results to events on versions created by that user. The email is resolved to a user in the authenticated organization before querying.

Query parameters

  • dateFrom string(date-time) Required

    Inclusive start of the date range (ISO 8601, UTC)

  • dateTo string(date-time) Required

    Inclusive end of the date range (ISO 8601, UTC). Must be at most 92 days after dateFrom.

  • storyId string

    Restrict events to a single story

  • versionId string

    Restrict events to a single version

  • userEmail string(email)

    Restrict events to versions created by the user with this email. Must match a user in the authenticated organization.

  • page integer

    1-indexed page number. Defaults to 1.

    Minimum value is 1. Default value is 1.

Responses

  • 200 application/json

    Events retrieved successfully

    Hide response attributes Show response attributes object
    • data array[object] Required
      Hide data attributes Show data attributes object
      • sessionId string | null
      • eventId string | null
      • visitorId string | null
      • timestamp string(date-time) Required
      • storyId string Required
      • storyTitle string | null
      • versionId string Required
      • versionTitle string | null
      • versionCreatedAt string(date-time) | null
      • prospectName string | null
      • prospectEmail string(email) | null
      • prospectPosition string | null
      • eventName string | null

        Specific action (e.g. view_slide_3, click_cta)

      • eventCategory string | null

        Always 'view' or 'click'

      • deviceType string | null
      • deviceTypeName string | null
      • eventUrl string(uri) | null
      • locationCity string | null
      • locationLatitude number(float) | null
      • locationLongitude number(float) | null
    • pagination object Required
      Hide pagination attributes Show pagination attributes object
      • page integer Required
      • pageSize integer Required
      • total integer Required
      • totalPages integer Required
      • hasMore boolean Required
  • 400 application/json

    Invalid request (missing/invalid params, range > 3 months, invalid token, etc.)

    Hide response attribute Show response attribute object
    • error string
  • 403 application/json

    Authentication failed, missing token, or account is not on the Team plan

    Hide response attribute Show response attribute object
    • error string
  • 404 application/json

    userEmail does not match any user in the organization

    Hide response attribute Show response attribute object
    • error string
  • 429 application/json

    Rate limit exceeded

    Hide headers attributes Show headers attributes
    • x-rate-limit-counter integer

      Current request count

    • x-rate-limit-maximum integer

      Maximum allowed requests per minute

    Hide response attribute Show response attribute object
    • error string
  • 500 application/json

    Internal server error

    Hide response attributes Show response attributes object
    • error string
    • errorId string
GET /v2/analytics/events 
curl \
 --request GET 'https://api.storydoc.com/v2/analytics/events?dateFrom=2026-01-01T00%3A00%3A00Z&dateTo=2026-03-31T23%3A59%3A59Z' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "data": [
    {
      "sessionId": "1c2f0c2c-9b7e-4f4a-9f8e-3a3a3a3a3a3a",
      "eventId": "evt_8a1c0a16d2b14e9c",
      "visitorId": "vis_aa11bb22cc33dd44",
      "timestamp": "2026-04-15T14:32:11.000Z",
      "storyId": "61b1e50223b713000a41ca74",
      "storyTitle": "Sales Presentation Template",
      "versionId": "65a1e50223b713000a41ca99",
      "versionTitle": "ACME Corp - Q2 Pitch",
      "versionCreatedAt": "2026-04-10T09:15:00.000Z",
      "prospectName": "Jane Cooper",
      "prospectEmail": "jane.cooper@acme.com",
      "prospectPosition": "VP Marketing",
      "eventName": "view_slide_3",
      "eventCategory": "view",
      "deviceType": "desktop",
      "deviceTypeName": "Mac",
      "eventUrl": "https://view.storydoc.com/abc123",
      "locationCity": "New York",
      "locationLatitude": 40.7128,
      "locationLongitude": -74.006
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 1000,
    "total": 12453,
    "totalPages": 13,
    "hasMore": true
  }
}
Response examples (400) 
{
  "error": "dateFrom and dateTo are required (ISO 8601, e.g. 2026-01-01 or 2026-01-01T00:00:00Z)"
}
{
  "error": "Date range cannot exceed 3 months"
}
{
  "error": "userEmail must be a valid email address"
}
{
  "error": "Token has been revoked"
}
Response examples (403) 
{
  "error": "Access denied"
}
{
  "error": "Analytics API is available on the Team plan only"
}
Response examples (404) 
{
  "error": "userEmail sender@company.com not found in this organization"
}
Response examples (429) 
# Headers
x-rate-limit-counter: 42
x-rate-limit-maximum: 42

# Payload
{
  "error": "Too many requests"
}
Response examples (500) 
{
  "error": "Error occured",
  "errorId": "550e8400-e29b-41d4-a716-446655440000"
}