> For the complete documentation index, see [llms.txt](https://docs.fullsession.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fullsession.io/20.-api-and-developer-tools.md).
# 20. API & Developer Tools
FullSession exposes a small, focused **REST API** for pulling your session data into your own systems, authenticated with **API tokens** you generate in the app. This chapter covers creating and managing tokens, the one available endpoint, authentication, rate limits, and — importantly — where the API's boundaries are.
API tokens are managed under **Settings → API Tokens**, governed by the `api_tokens:view`, `api_tokens:create`, and `api_tokens:delete` permissions (\[Chapter 16 — Team & Account Management]).
***
### 20.1 What the API Offers
Set expectations first: FullSession's public API is intentionally narrow. It provides **one read-only endpoint** — listing sessions for a site — authenticated by a token scoped to one or more of your sites.
It helps to know where the API fits among FullSession's three developer-facing surfaces, which are easy to confuse:
| Surface | Direction | Purpose | Where it's covered |
| --------------------------------------------------------- | --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tracker SDK** (`FUS.identify`, `FUS.event`, …) | Browser → FullSession | Send identity, events, and attributes *in* | [Chapters 3](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610#), [4](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610#), [7](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610#) |
| **Integrations** (Intercom, HubSpot, Optimizely, Zapier…) | FullSession ↔ third parties | Connect to specific tools | [Chapter 19](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610#) |
| **REST API** (this chapter) | FullSession → your code | Pull session data *out* | This chapter |
> If you're looking to *send* data in, that's the **tracker SDK** (\[Chapter 3, section 3.5]). The REST API is only for *reading* session data out.
***
### 20.2 API Tokens
API tokens authenticate your requests. You can create multiple tokens, each scoped to specific sites.
#### Creating a token
1. Click **Create New Token** (requires `api_tokens:create`).
2. Provide:
* **Token name** *(required)* — must be unique.
* **Description** *(optional)*.
* **Permissions** — choose **All** (every site in your account) or **Specific Sites** (pick the sites this token may access).
3. Click **Create**.
#### Copy it now — it's shown only once
When the token is created, FullSession displays the full token value **once**, with the message *"You will only see the token ONCE, so make sure to copy it now."* Copy it immediately and store it securely. Afterward, the app only ever shows an **obfuscated** form (e.g. `fus_****abc`) — the full value can't be retrieved again.
#### Token scope
Tokens are scoped by **site**, not by action:
| Scope | Access |
| ------------------ | --------------------------- |
| **All** | Any site in your account |
| **Specific Sites** | Only the sites you selected |
> **Tokens are not granularly scoped.** There are no "read-only" vs. "write" or per-resource scopes — within its site scope, a token can call the available endpoint. (The API itself is read-only, so a token can only read sessions.)
#### Managing tokens
| Action | Available? |
| -------------------------------------- | --------------------- |
| **Create** multiple tokens | ✅ |
| **List** your tokens (obfuscated) | ✅ |
| **Delete / revoke** a token | ✅ |
| **Edit** a token's name/description | ❌ Not supported |
| **Regenerate** a token (keep the name) | ❌ Not supported |
| **Expiration / TTL** | ❌ Tokens don't expire |
| **Last-used tracking** | ❌ Not tracked |
> **Tokens are permanent until deleted, and don't expire.** Treat each token like a password. To "rotate" a token, **delete** the old one and **create** a new one, then update your integration with the new value. Deleting a token immediately revokes its access.
***
### 20.3 The Sessions API
The single public endpoint lists sessions for one of your sites.
#### Endpoint
```
GET /v1/external/sessions/{customerId}/{siteId}
```
* **`{customerId}`** — your account's Customer ID.
* **`{siteId}`** — the site to read sessions from (the token must be scoped to this site).
#### Authentication
Pass your token as a **Bearer** token in the `Authorization` header:
```
Authorization: Bearer fus_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
#### Query parameters
All are optional:
| Parameter | Meaning |
| ---------------- | ---------------------------------------------------------------- |
| **`startTime`** | Only sessions starting at/after this time (Unix milliseconds) |
| **`endTime`** | Only sessions ending at/before this time (Unix milliseconds) |
| **`startAfter`** | Pagination cursor — pass the value returned by the previous page |
#### Example request
```bash
curl -H "Authorization: Bearer fus_xxxxxxxx..." \
"https:///v1/external/sessions/YOUR_CUSTOMER_ID/YOUR_SITE_ID?startTime=1717200000000&endTime=1717286400000"
```
#### Response
```json
{
"data": {
"startAfter": 1717250000000,
"sessions": [
{ "...session fields (id, user, pages, duration, timestamp, …)..." }
]
}
}
```
#### Pagination
* The endpoint returns **up to 1,000 sessions per request**.
* To page through more, take the **`startAfter`** value from the response and pass it as the `startAfter` query parameter on your next call.
* Repeat until `startAfter` is no longer returned (you've reached the end).
```
1. GET …/sessions/{customerId}/{siteId}?startTime=…&endTime=…
2. Read data.startAfter from the response
3. GET …?startTime=…&endTime=…&startAfter=
4. Repeat until no startAfter is returned
```
> **Tip** — drive bulk syncs by time window: page through a window with `startTime`/`endTime`, then advance the window. Keep each token's request volume within the rate limit (next section).
***
### 20.4 Rate Limits
The external API is rate-limited:
> **20 requests per minute** across the `/v1/external` API.
This limit applies to the external API as a whole (it isn't tracked per individual token), so coordinate your jobs if several processes share access. Build in backoff and pacing so a bulk sync stays under the limit — combined with the 1,000-sessions-per-request page size, 20 requests/minute is enough to move a large volume of sessions steadily.
***
### 20.5 What the API Doesn't Include
To plan integrations accurately, know the boundaries. These **don't exist**:
* **No other endpoints.** The only public endpoint is **list sessions** (section 20.3). There's **no API** for funnels, segments, segment stats, dashboards/cards, events, or full-text session search.
* **No programmatic data export.** CSV export is a **UI-only** feature (from dashboard cards, capped at 10,000 rows — \[Chapter 9, section 9.8]); there's no export-via-API.
* **No developer webhooks.** FullSession doesn't push events to your endpoints. Outbound automation goes through **Zapier** and the **Slack alert hook** ([Chapters 15](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610#) & [19](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610#)) — neither of which uses API tokens.
* **No granular scopes, token expiry, regeneration, or last-used tracking** (section 20.2).
* **No in-app API reference or public OpenAPI/Swagger spec.** Use this chapter as the reference for the available endpoint.
#### A note on the internal Dev Tools page
You may see a `Settings → Dev Tools` page referenced in the app. It's an **internal FullSession support/impersonation tool**, not a customer-facing developer feature — regular accounts don't have access to it, and it's unrelated to API tokens.
> **The big picture** — FullSession's API is small and read-only: generate a **site-scoped token** under **Settings → API Tokens** (copy it once — it's shown only once and never expires), then call the single **`GET /v1/external/sessions/{customerId}/{siteId}`** endpoint with `Authorization: Bearer fus_…`, paging via `startAfter` at up to **1,000 sessions per request** and **20 requests/minute**. For sending data *in*, use the **tracker SDK**; for tool connections, use **Integrations**; for automation, use **Zapier/alerts** — none of which are part of this API.
***
> **Next up:** \[Chapter 21 — Privacy, Security & Compliance] covers what FullSession records and how to control it — masking, excluded users, IP and recording rules, and data retention.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fullsession.io/20.-api-and-developer-tools.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.