---
title: "Query analytics events"
method: GET
path: "/v2/analytics/events"
tags: ["analytics"]
---

# Query analytics events

`GET /v2/analytics/events`

## Request

- Base URL: `https://api.storydoc.com`
- URL: `https://api.storydoc.com/v2/analytics/events`
- Auth: HTTP bearer

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
- `dateTo` string, date-time, required
- `storyId` string
- `versionId` string
- `userEmail` string, email
- `page` integer

## Response `200`

Events retrieved successfully

- AnalyticsEventsResponse
  - `data` AnalyticsEventRow[], required
    - `sessionId` string, nullable
    - `eventId` string, nullable
    - `visitorId` string, nullable
    - `timestamp` string, date-time, required
    - `storyId` string, required
    - `storyTitle` string, nullable
    - `versionId` string, required
    - `versionTitle` string, nullable
    - `versionCreatedAt` string, date-time, nullable
    - `prospectName` string, nullable
    - `prospectEmail` string, email, nullable
    - `prospectPosition` string, nullable
    - `eventName` string, nullable: Specific action (e.g. view_slide_3, click_cta)
    - `eventCategory` string, nullable: Always 'view' or 'click'
    - `deviceType` string, nullable
    - `deviceTypeName` string, nullable
    - `eventUrl` string, uri, nullable
    - `locationCity` string, nullable
    - `locationLatitude` number, float, nullable
    - `locationLongitude` number, float, nullable
  - `pagination` object, required
    - `page` integer, required
    - `pageSize` integer, required
    - `total` integer, required
    - `totalPages` integer, required
    - `hasMore` boolean, required

## Other responses

- `400`: Invalid request (missing/invalid params, range > 3 months, invalid token, etc.)
- `403`: Authentication failed, missing token, or account is not on the Team plan
- `404`: userEmail does not match any user in the organization
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/storydoc/apis/storydoc-api-v2.md) - [All operations](https://skmtc.dev/storydoc/apis/storydoc-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/storydoc/apis/storydoc-api-v2/revisions/366e7d124e9e?raw)