A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Fullstory API is how an app or AI agent works with a Fullstory account: listing a user's sessions, reading the events captured in a session, sending users and custom events back in, and generating AI summaries of what a person did. Access is granted through a server API key, and the key's permission level, Standard, Architect, or Admin, decides which methods it can call and how far it can read or export. Fullstory can also push account activity, like a segment alert or a note added to a session, to a registered webhook endpoint.
How an app or AI agent connects to Fullstory determines what it can reach. There is the Server API for sending and reading data, a set of outbound webhooks for receiving events, and a hosted server that exposes Fullstory tools to agents, and each is governed by the key behind it and the permission level that key carries.
The Server API answers at https://api.fullstory.com, where the modern methods sit under v2 and the segment, export, and webhook methods remain on v1. A request authenticates with an API key sent in an Authorization header using Basic auth, and the key is automatically routed to the account's data center.
Fullstory POSTs an event to an HTTPS endpoint registered through the Webhooks API when something happens in the account, such as a saved segment crossing an active-user threshold or a teammate adding a note. Each delivery carries a Fullstory-Signature header with the organization id, a Unix timestamp, and a base64 HMAC-SHA256 signature, which the receiver recomputes with the shared secret to confirm the request came from Fullstory and is recent.
A hosted Model Context Protocol server at https://api.fullstory.com/mcp/fullstory connects AI clients like Claude, Cursor, and ChatGPT to Fullstory behavioral data, so they can ask natural-language questions without leaving the workflow. It authenticates through an OAuth flow, exposes analytics tools such as compute_metric, and depends on StoryAI being enabled. As of June 2026 it is in private beta and must be enabled per account.
A server API key authenticates every call, sent in an Authorization header using Basic auth. The key format is .
Every API key carries one of three permission levels that form a hierarchy: Standard can send data and list sessions, Architect adds reading and exporting user data, segments, and raw exports (Enterprise plans), and Admin adds privacy-critical configuration. A higher level can call every endpoint available to the levels below it, so the level is what bounds an agent.
The hosted MCP server authenticates a connecting AI client through an OAuth authorization flow rather than an API key, and the tools an agent sees depend on StoryAI being enabled for the organization.
The Fullstory API is split into areas an agent can act on, like sessions, users, events, segments, and exports. Each area has its own methods, and reading session replay or exporting segment data returns the behavior of real, identifiable people.
List a user's recent sessions, read the full set of captured events for a session, and generate AI context and summaries from a session.
Create, read, list, update, and delete the prompt-and-context profiles that drive AI session summaries.
Create or update a user, read and list users, delete a user, and import users in bulk or as a stream.
Create a single custom event tied to a user or session, and import events in bulk through a batch job.
List and read saved segments, and schedule an export of the individuals or events in a segment.
Schedule and retrieve raw data exports of user events and pages, and fetch the results of a search export.
List, read, create, update, and delete the webhook endpoints that receive Fullstory's outbound events.
Read the account's quota usage for captured sessions and server events.
Create an annotation to mark a moment of note on the account timeline.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SessionsList a user's recent sessions, read the full set of captured events for a session, and generate AI context and summaries from a session.5 | ||||||
| GET | /v2/sessions | List a user's most recent sessions, queried by uid and/or email, returning session replay links. | read | Standard | Current | |
Needs a Standard key or higher. If both uid and email are given, it queries each separately and returns the union. Acts onsession Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/sessions/{session_id}/events | Return the full set of captured events for a single session. | read | Standard | Current | |
Needs a Standard key or higher. The session id is the canonical user_id:session_id form. Acts onsession Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/sessions/{session_id}/context | Generate a context response with the session information and events, structured as JSON for an AI model. | read | Standard | Current | |
Needs a Standard key or higher. A POST that reads a session and returns a model-ready context, it does not change the session. Acts onsession Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/sessions/{session_id}/summary | Generate an AI summary of a session using a named summary profile. | read | Standard | Current | |
Needs a Standard key or higher, and requires StoryAI to be enabled on the account. Acts onsession Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/sessions/{session_id}/summary | Generate an AI summary of a session, overriding profile parameters per request. | read | Standard | Current | |
Needs a Standard key or higher. A POST that returns generated text, it does not change the session. Acts onsession Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Summary profilesCreate, read, list, update, and delete the prompt-and-context profiles that drive AI session summaries.5 | ||||||
| POST | /v2/visit_profile | Create a summary profile that defines prompting instructions and session context configuration. | write | Standard | Current | |
Needs a Standard key or higher. The endpoint path uses Fullstory's internal visit_profile name for a summary profile. Acts onsummary profile Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/visit_profile/{id} | Return a single summary profile. | read | Standard | Current | |
Needs a Standard key or higher. Acts onsummary profile Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/visit_profile | List the summary profiles defined on the account. | read | Standard | Current | |
Needs a Standard key or higher. Acts onsummary profile Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/visit_profile/{id} | Update an existing summary profile. | write | Standard | Current | |
Needs a Standard key or higher. Acts onsummary profile Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/visit_profile/{id} | Delete a summary profile. | write | Standard | Current | |
Needs a Standard key or higher. Acts onsummary profile Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersCreate or update a user, read and list users, delete a user, and import users in bulk or as a stream.8 | ||||||
| POST | /v2/users | Create or update a user with the specified details (an upsert). | write | Standard | Current | |
Needs a Standard key or higher. Up to 500 unique properties are allowed per user. Acts onuser Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{id} | Retrieve details for a single user. | read | Architect | Current | |
Reading user data needs an Architect key or higher, available on Enterprise plans. Acts onuser Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users | Retrieve a list of users matching the supplied filter criteria. | read | Architect | Current | |
Reading user data needs an Architect key or higher. Acts onuser Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/{id} | Update a user with the specified details. | write | Standard | Current | |
Needs a Standard key or higher. Acts onuser Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/users/{id} | Delete a single user. | write | Architect | Current | |
Deleting a user needs an Architect key or higher, and removes that person's captured data. Acts onuser Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/batch | Create a batch user import job from a list of users' information. | write | Standard | Current | |
Needs a Standard key or higher. A batch import accepts up to 50,000 records per request. Acts onuser import job Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/batch/{job_id} | Get the status and job details for a batch user import job. | read | Standard | Current | |
Needs a Standard key or higher. Acts onuser import job Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/stream | Create a user asynchronously through a stream import, returning a request id to query for status. | write | Standard | Current | |
Needs a Standard key or higher. Acts onuser Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsCreate a single custom event tied to a user or session, and import events in bulk through a batch job.3 | ||||||
| POST | /v2/events | Create one custom event with the specified details, tied to a user or session. | write | Standard | Current | |
Needs a Standard key or higher. A server event counts against the account's server event quota. Acts onevent Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/events/batch | Create a batch events import job from a list of event information. | write | Standard | Current | |
Needs a Standard key or higher. A batch import accepts up to 50,000 records per request. Acts onevent import job Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/events/batch/{job_id} | Get the status and job details for a batch events import job. | read | Standard | Current | |
Needs a Standard key or higher. Acts onevent import job Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Segments (v1)List and read saved segments, and schedule an export of the individuals or events in a segment.3 | ||||||
| GET | /segments/v1 | List the saved segments on the account. | read | Architect | Current | |
A v1 method. Listing and exporting segments needs an Architect key, available on Enterprise plans. Acts onsegment Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /segments/v1/{id} | Read a single saved segment. | read | Architect | Current | |
A v1 method needing an Architect key. Acts onsegment Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /segments/v1/exports | Schedule an export of the individuals or events in a segment. | write | Architect | Current | |
A v1 method needing an Architect key. Segment Export is an Enterprise or Advanced add-on, and the export pulls the behavior of every matching person. Acts onsegment export Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Exports (v1)Schedule and retrieve raw data exports of user events and pages, and fetch the results of a search export.3 | ||||||
| GET | /search/v1/exports/{id}/results | Fetch the results of a completed search or segment export. | read | Architect | Current | |
A v1 method needing an Architect key. Returns the rows of a prepared export. Acts onexport Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/export/userEvents | Retrieve a raw data export of user events for a prepared export. | read | Architect | Current | |
A legacy v1 Data Export method needing an Architect key. Fullstory recommends the Segment Export API for new work. Acts onexport Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/export/list | List the available raw data exports. | read | Architect | Current | |
A legacy v1 Data Export method needing an Architect key. Acts onexport Permission (capability) ArchitectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhooks (v1)List, read, create, update, and delete the webhook endpoints that receive Fullstory's outbound events.4 | ||||||
| GET | /webhooks/v1/endpoints | List the webhook endpoints registered to receive Fullstory's outbound events. | read | Admin | Current | |
A v1 Webhooks method. Managing webhook endpoints is an account-configuration action handled with an Admin key. Acts onwebhook endpoint Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks/v1/endpoints | Register a webhook endpoint and the events it should receive. | write | Admin | Current | |
A v1 Webhooks method handled with an Admin key. It sets where Fullstory delivers event data. Acts onwebhook endpoint Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /webhooks/v1/endpoints/{id} | Read a single webhook endpoint. | read | Admin | Current | |
A v1 Webhooks method handled with an Admin key. Acts onwebhook endpoint Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /webhooks/v1/event-types | List the event types that can trigger a webhook. | read | Admin | Current | |
A v1 Webhooks method handled with an Admin key. Acts onwebhook event type Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationRead the account's quota usage for captured sessions and server events.1 | ||||||
| GET | /v2/organization/quotas | Return all quota usage for the organization, including session and server event quotas. | read | Standard | Current | |
Needs a Standard key or higher. Acts onquota Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AnnotationsCreate an annotation to mark a moment of note on the account timeline.1 | ||||||
| POST | /v2/annotations | Create an annotation with the specified details. | write | Standard | Current | |
Needs a Standard key or higher. Acts onannotation Permission (capability) StandardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Fullstory can notify an app when something happens in an account, like a saved segment crossing an active-user threshold or a teammate adding a note to a session. It posts the event to a webhook endpoint registered through the Webhooks API, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
segment.created | Fires when a user of Fullstory creates a new segment. | In-app only |
segment.trend.alert | Fires when a segment-based alert triggers, such as the active users in a saved segment crossing a configured threshold. | In-app only |
metric.alert | Fires when a metric alert triggers. | In-app only |
note.created | Fires when a user of Fullstory makes a note on a recorded session. | In-app only |
nativemobile.event.crash | Fires when a native mobile app has crashed. | In-app only |
Fullstory limits how fast an app can call, with one limit on requests per second and another that smooths short bursts, plus account quotas on captured sessions and on server events.
Fullstory guards the API against bursts of traffic with two limiters: one caps the number of requests received in any given second, set high enough that it should not be hit under realistic load, and another smooths short bursts that exceed the standard rate and then recharges over time. Sending many requests in quick succession returns an HTTP 429, and the response includes a Retry-After header giving the number of seconds to wait before retrying. Separately, the account has quotas on captured sessions and on server events, and a request that exceeds the server event quota also returns 429.
List endpoints return a page of results with a token to fetch the next page, and an endpoint that supports it accepts a limit parameter to set the page size. List Sessions returns up to limit of a user's most recent sessions, queried by uid and/or email.
A batch import job, for users or for events, accepts up to 50,000 records per request. A user may carry up to 500 unique custom properties. Per-endpoint payload limits, where they apply, are stated on each endpoint's reference page.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | Invalid input has been provided in the request. | Read the code and message in the response body, fix the input, and retry. |
| 401 | unauthorized | Access to the resource is unauthorized, usually a missing or invalid API key. | Send a valid API key in the Authorization header using Basic auth. |
| 403 | forbidden | Access is not allowed due to insufficient permissions on the key. | Use a key with a higher permission level, such as Architect for reading or exporting user data. |
| 404 | not_found | The requested resource does not exist. | Verify the id in the path and that the resource belongs to this account. |
| 429 | too_many_requests | A rate limit or the server event quota was exceeded. The response carries a Retry-After header with the seconds to wait. | Wait the number of seconds given in the Retry-After header, then retry with backoff. |
| 500 | internal_error | A server error was encountered on Fullstory's side. | Retry with backoff, and contact Fullstory support if it persists. |
Fullstory introduced version 2 of its Server API in August 2023, its first major version bump, served alongside the earlier version 1 that still carries the segment, export, and webhook methods.
Fullstory released version 2 of the Server API in August 2023, the first major version bump in its history. It is initially focused on enhanced data capture and processing, drops the type suffixes v1 required on custom properties, and lets a user be created without a prior session. Sessions, users, and events live on v2, served alongside the v1 segment, export, and webhook methods.
In May 2026 Fullstory added a Customer Agents MCP server, giving AI-powered tools real-time behavioral context from user sessions.
In April 2026 Fullstory launched its MCP server, connecting AI clients like Claude Code and Cursor directly to Fullstory product data through an OAuth flow. It is in private beta and must be enabled per account.
August 2023: Fullstory announced version 2 of the API, its first major version bump, covering the new users and events endpoints.
Build new integrations on v2, and use v1 for the export, segment, and webhook methods v2 does not yet cover.
Fullstory release notes ↗Bollard AI sits between a team's AI agents and Fullstory. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.