# Quickstart: your first hour with Sequential

> Ten steps take you from a new account to your first judged sessions. Each step says how to check that it is done and links to more detail.

> **In short**
>
> - Create an organisation and a project, then install one source.
> - Check on **Setup** that your source shows "receiving".
> - Identify your users and send custom events for key moments.
> - Check masking, open a replay, then look at **Watch**.
> - Tailor the rubric and invite your team.
> - Optional: connect your coding agent to Sequential.

## What you need

- An account with a verified email address. Anyone can create an account. A coding agent can also set up a trial for you before you have one: [Let your agent set up a trial](/docs/agent-trial). See [Sign-up and invitations](/docs/sign-up-and-invitations).
- Your app's code, or a developer with access to it.
- The owner or admin role, for steps 6, 9 and 10, and to connect an agent.

## 1. Create your organisation and project

1. Enter an **Organisation name** and press **Continue**.
2. Enter a **Project name** and press **Continue**.

**Done when:** the **Install** step shows code with your project's keys.

### Onboarding, the install code and other environments

After sign-up, onboarding shows four steps: **Organisation**, **Project**, **Install** and **Agent**. A project is one app or site. The person who creates the organisation is its owner. See [Organisations, projects and keys](/docs/organisations-and-projects).

The **Install** step has two tabs. It opens on **Ask your coding agent**: press **Copy prompt** and give the prompt to your agent. On **Paste the snippet**, press **Copy snippet** to copy the code for the source that you picked. The button then reads **Copied**. Then open your app in a normal browser.

From 15 October 2026, a card next to the code listens for your first event. On a narrow screen, the card is below the code. It shows one of these lines:

- "Listening for your first event…": nothing arrived yet.
- "Your app reached Sequential. The first events show here within about a minute.": a request with your key arrived. If no event is stored 2 minutes later, the card says when the requests arrived, "but no events are stored." It also says "Sequential doesn't store visits from automated browsers". For example, an agent that checks the install with a headless browser causes this.
- "Your app is sending. The first events show here within about a minute.": Sequential has data from your app, but no event that it can show yet.
- **It works**, the number of events in the last 24 hours and the host of the newest event, such as "12 events · newest from shop.example.com".
- The pause message, when recording is paused for the organisation.

The card checks every 5 seconds, only while the tab is visible, for 30 minutes. Then it says "Stopped checking after 30 minutes." and shows **Check again**. When you come back to the tab, it checks at once.

When events arrive, the card lists the 5 newest, each with its name, host and time. It shows no property values. An identify call reads "Identified a visitor". The list updates for 2 minutes. After that, press **Refresh**. With **It works**, the card also shows the **Browser** of the newest event and a **Replay** line: "Checking recording…", "Recording · ready by" and a time, **Recorded** with **Watch the session**, or "Couldn't check recording". It shows "No recording" only from 60 seconds after the newest event.

If Sequential refused data from your app in the last 7 days, the card shows the reasons and the fixes until it says **It works**. See [Troubleshooting](/docs/troubleshooting).

Under the card are two links: **Read the install guide** and **Nothing arrives? What to check**. On **Paste the snippet**, under the code, the step says "A public key: it is safe in your page's source." On both tabs, the step says that Session replay masks all text and inputs by default, with a link to **Masking options**.

Until the card says **It works**, the button at the bottom is **Skip for now**, with "This step waits on your dashboard." After that, the button is **Continue**. Both open the **Agent** step. See [Connect your agent](#connect-your-agent).

From 15 October 2026, after onboarding creates the project, the address reads `/onboarding?project=<id>&step=install`, and `step=agent` on the **Agent** step. It holds only these two values. A reload, or a phone that closes the tab, opens the same step again, with the same project and its keys. This works only for a project that is not archived, in an organisation where your role can create projects: owner or admin. Otherwise onboarding starts again. If the keys cannot load after a reload, the **Install** step says "Sequential could not load this project's keys." with **Try again**.

You can find the install code later in Settings → Projects → your project → **Setup**.

Onboarding always creates a production project.

To add a staging or development project, go to Settings → Projects → **New project**. Choose the **Environment**. A project of this kind records 10 % of sessions by default. See **Sampling** in its Session replay settings.

## 2. Install

Choose your path in [Install Sequential](/docs/install):

- **Website, no analytics yet:** use the [Sequential SDK](/docs/sequential).
- **PostHog, Mixpanel, Amplitude or Pendo:** send your SDK's data to Sequential. For replays, add the [Session replay (web)](/docs/session-replay) line.
- **Smartlook:** send your snippet's data to Sequential. See [Moving from Smartlook](/docs/smartlook).
- **Mobile app:** use PostHog's mobile SDK. See [Mobile apps](/docs/mobile).

Each key works for one source only.

**Done when:** the change is live somewhere you can open in a normal browser.

### Install with a coding agent, and what starts the recorder

1. On **Setup**, under **Install with your AI agent**, press **Copy prompt**. The prompt includes your keys.
2. Paste it into your coding agent.

**Setup** shows the code with your keys filled in.

On websites, the Sequential SDK and the Smartlook script start the recorder for you. With PostHog, Mixpanel, Amplitude or Pendo, the recorder is the extra line from step 2.

## 3. Check that events arrive

With **Setup** open, visit your site in a normal browser. Sequential rejects automated browsers as bots.

**Done when:** your source reads "receiving" on the **Sources** card. The **Sequential** line changes from "no events yet" to "receiving". The line of another SDK, such as PostHog, shows only from its first event, as "receiving". **Session replay**, if you installed it, also changes to "receiving", but it can take longer: see below. If you are stuck, see [Check your install](/docs/verify).

The **Sources** card checks for 5 minutes. To keep checking, reload the page.

> **Note**
>
> The waiting message stays while any source is silent, even one you do not use. Read your own line.

### How the Sources card checks

- The **Session replay** line changes after a page visit longer than the minimum recording length. The default is 2 s.
- The **Sources** card checks again every few seconds for 5 minutes. To keep checking, reload the page.
- Session replay can take up to about 7 minutes to show "receiving". The card checks for 5 minutes, so reload the page if it has not changed.
- A first event can take up to about a minute to appear. When one line shows "receiving", the other lines can take up to about two minutes to update.
- To change the minimum recording length, see **Skip sessions under (ms)** in the project's Session replay settings.

## 4. Identify your users

Until you identify a visitor, Sequential counts them as a new user on every device.

- **Sequential SDK:** call `sequential.identify(userId)` at sign-up, at sign-in, and on page load if the user is signed in. Call `sequential.reset()` at sign-out.
- **Vendor SDK:** keep its own identify call.
- Pass the same value every time for a given person. Two different values, such as an email at sign-up then an account id, make two users.

**Done when:** after a test sign-in, **Users** lists you by the value you passed to `identify`, or by a name or email that you passed with it. Hover your avatar: it reads **Identified user**. See [Identify your users](/docs/identify-users).

> **Some pages do not join earlier events yet**
>
> With the Sequential SDK, PostHog or Mixpanel, **Users**, the user page, funnels, flows, retention and **Events** count the events sent before identify under the value you passed. This can take up to 5 minutes. The **Dashboard** tiles still count the anonymous id as a separate user. On the **Traffic** tile, this figure is labelled **User IDs**, with the hover text "Distinct user ids. A visitor who signed in during a visit counts once per id they used." On the **Top pages** tile, each row reads like "12 user IDs". With a vendor SDK, **Users** also lists the anonymous id as a separate user.

### Which value to pass

A user id, an email or an account key all work. Sequential uses the value exactly as you pass it.

Until you identify a visitor, their events carry an anonymous id for each browser. Sequential stores the events sent before identify under the anonymous id.

With a vendor SDK, **Users** also lists the anonymous id from before your test sign-in. With the Sequential SDK, PostHog or Mixpanel, it lists that id only until the link to your value shows, up to 5 minutes later.

## 5. Send custom events for key moments

Send one event for each business moment, such as starting checkout. Give it a stable name, such as `checkout_started`. Put the details in properties.

Filters match the name, not properties. So moments you filter separately need different names.

With the Sequential SDK, call `sequential.capture(name, props)`. Names that start with `$` are reserved. `capture()` throws an error on them.

**Done when:** your event appears on **Events** under **Individual user actions** with a **Custom** badge. See [Send custom events](/docs/custom-events).

### Event names and where events are used

- The Sequential SDK captures page views, clicks and form submits itself.
- Business moments need their own events. Other examples are signing up and inviting a teammate.
- Names that start with `$` are reserved. `capture()` throws an error on them.
- Vendor calls such as `mixpanel.track` keep their names.
- You can use custom events as funnel steps. The judge also reads them. See steps 8 and 9.

## 6. Check replay and masking settings

In Settings → Projects → your project → **Session replay**, check:

- **Masking:** **Strict** is the default. It masks all text, inputs and most attribute values, so replays show only the page layout.
- **DevTools:** keep **Record message text** off in production until you know what your app logs.
- **Mobile apps:** you set masking in the app's PostHog SDK.

**Done when:** the summary line shows recording **On**, the share of sessions you expect, and your masking. See [Recording settings](/docs/recording-settings) and [Masking and redaction](/docs/masking-and-redaction).

### What Strict masking and DevTools capture

Replay is on for new projects.

With **Strict** masking, replays look like a wireframe.

Sequential captures errors, console, network and performance by default.

### Change to Balanced masking

**Strict** also blocks images, SVG, media and iframes. It cuts link and image addresses to their domain, so web fonts and CSS background images do not load in the replay.

**Balanced** masks all inputs. It masks only the text you mark with `data-sq-mask` or the `sq-mask` class. It records images and SVG. It still blocks video, audio and iframes. It records attribute values and the full page address. See [Masking and redaction](/docs/masking-and-redaction).

To change to **Balanced**:

1. Mark the sensitive elements in your app.
2. Choose **Balanced**.
3. Press **Save**.
4. Under **Loosen masking?**, type the project slug.
5. Press **Apply**.

Changes apply from the next page load. They never apply to earlier recordings.

You set mobile masking in the app's PostHog SDK.

## 7. Open a replay

In **Sessions** → **Latest**, press **▶ Replay** (**Play session replay**). A recording can take up to about 6 minutes after its last upload to become playable.

**Done when:** the recording plays with your events as timeline markers and in the **Events** panel. See [Find and replay sessions](/docs/sessions-and-replay).

### When a recording is missing or shows no events

In **Latest**, if you cannot play the session now, the row says why in place of **▶ Replay**. "Processing · ready by 14:05", with a time, means that Sequential is still preparing the recording in 5-minute periods. Wait until that time. The row then shows ▶ without a reload.

Sequential builds the **Latest** list from analytics events. So a recording appears only if the same session also sent events.

If the recording shows no events, the recording and the events had different session ids. See [Troubleshooting](/docs/troubleshooting).

### The Insights tab

The **Insights** tab judges the session on demand, from a daily allowance per project.

If you press **Re-run** a second time on the same session within 10 minutes of the previous run, you get the saved result. The judge does not judge the session again.

See [Session insights](/docs/session-insights).

## 8. Look at Watch

Go to **Sessions** → **Watch**. It ranks judged sessions, most worth watching first. If it shows a message:

| Message | What it means |
|---|---|
| "Background judging is switched off for this project." | An owner or admin turned it off. Turn it on under **Settings** → **Projects** → your project → **Insights**. |
| Another reason why background judging is off | See [Watch](/docs/watch). |
| "Nothing judged yet" | The judge has not judged a session in the date range yet. |

**Done when:** you see ranked rows. See [Watch](/docs/watch) and [Reading a verdict](/docs/reading-verdicts).

### When a session is judged, and what a row shows

Each row has a short reason. It also has **Watch from** *m:ss*, **Open replay** or **Open events**.

- The judge judges a session with at least 3 meaningful events. System events do not count.
- Judging starts about 30 minutes after the session's last event.
- The judge reads the session's events, not the recording.
- A 👍 or 👎 on a row you checked records whether the row was right. The judge does not judge the session again.

## 9. Tailor the rubric

The rubric is the judge's questions about each judged session.

1. Open Settings → Projects → your project → **Insights**.
2. Add a question.
3. In **Try it**, pick a recent **Session** and press **Run**.
4. Press **Save**.

**Done when:** the header badge reads **Customised**, not **Default rubric**. The judge uses your changes only for sessions judged after you save. See [Customise the rubric](/docs/rubric).

### Good questions and what changes after you save

The default rubric is generic. It cannot know your product's own moments, such as reaching bulk upload.

For a yes-or-no question, press **+ Add signal**. In **Try it**, the judge answers your draft before you save it.

A good question:

- can be answered by the judge from events, session facts and error counts. The judge never sees the screen.
- asks one thing.
- asks what happened, not how someone felt. For example: "Did they click the same control repeatedly?"

**Try it** has its own daily allowance. So it does not use the allowance of background judging.

After you save, older sessions show "judged with an earlier rubric" in Watch. If you change what the judge asks, the **Calibration** counts also start again.

## 10. Invite your team

1. Go to Settings → **Organisation**.
2. Under **Members**, enter an **Email** and choose a **Role**.
3. Press **Send invitation**.

Invitations expire after 48 hours. To accept, a teammate signs in with the invited address. That address must be verified.

**Done when:** your teammates are under **Members**, not **Pending invitations**.

### Resend an invitation, and what each role can do

See [Roles and permissions](/docs/roles-and-permissions).

A role covers every project in the organisation.

To accept, a teammate signs in with the invited address. That address must be verified.

If you press **Resend** under **Pending invitations**, the 48 hours start again.

| Role | In the app |
|---|---|
| Owner | Full control, including deleting the organisation. |
| Admin | Manages members, projects, keys and settings. |
| Member | Explores analytics and replays. Can use AI. |
| Viewer | Read-only access to analytics and replays. |

## Connect your agent

This step is optional. It lets a coding agent, such as Claude Code or Cursor, read your sessions, verdicts and findings over MCP. You need the owner or admin role.

In onboarding:

1. On the **Install** step, press **Skip for now**, or **Continue** after the card says **It works**. The **Connect your agent** step opens.
2. Pick your agent: **Claude Code**, **Cursor**, **Codex**, **Other MCP clients (JSON)** or **Claude Desktop**. For **claude.ai**, you create no token. Follow [Connect claude.ai](/docs/connect-claude-ai). For Claude Code, [Connect Claude Code](/docs/connect-claude-code) gives every step.
3. Press **Create token**. Sequential creates a token with the scopes of **Agent: read everything, plus Ask**. It expires in 90 days. The token includes `analytics:read`, so your coding agent can use the analytics tools. See [Analytics from an agent](/docs/limits#analytics-from-an-agent).
4. Copy the setup for your agent. It contains the real token. Add it to your agent's user-level settings, not to a file in your repository. The note under the setup tells you where it goes. The step shows only the setup for the agent that you picked. **Other clients** is closed at first. Open it for the setups of the other agents and the **Read-only endpoint (no write tools)**. They also contain the real token.
5. Ask your agent a question. The step suggests one: "Using Sequential, what should I know about my product this week?"

Later, open **Agents** in the left rail. Under **Your agents**, the **Coding agents** card says "Claude Code, Cursor, Claude Desktop and other tools that take an access token." It lists the tokens that can still work. Each row shows the token's name in quotes and who created it, for example `"Agent on 29 Sept 2026" · by Ana`. Your own tokens say "by you". A teammate's token shows their name, or their email address when their name is blank. If the account of the person who created it was deleted, the row says "by a teammate". A trial's agent token shows "by the agent that set up this trial". With no token, the card shows two steps: "Create an access token." and "Copy the setup line for your tool and run it." To make a new one, press **Set up a coding agent**. It opens **Advanced: create an access token**, selects **Agent: read everything, plus Ask** and moves the focus to **Create token**. If you already chose **Custom…** there, it keeps your choice. The form already has a name: "Agent on" and the date of today, for example "Agent on 29 Sept 2026". Press **Create token**. The new token shows once, with the setups for **Claude Code**, **Cursor** and **Claude Desktop**. They have the token filled in.

On the **Access tokens** tab (Settings → Projects → your project), the **Connect an agent** card starts with: "Give a coding agent or a CI job its own token, then add the Sequential endpoint to it. In the snippets that use a token, replace `<token>` with the token you created." When the card shows the claude.ai connector URL, it adds: "claude.ai connects with its own sign-in, no token."

What each setup is, and where it goes:

| Agent | The setup | Where it goes |
|---|---|---|
| Claude Code | A `claude mcp add` command with `--scope user` | Run it once. It adds Sequential for every project on the computer. |
| Cursor | JSON with `url` and an `Authorization` header | `~/.cursor/mcp.json`, not the `.cursor/mcp.json` of a project |
| Codex | TOML: `[mcp_servers.sequential]` with `url` and `http_headers` | `~/.codex/config.toml` |
| Other MCP clients (JSON) | The same JSON as Cursor | The user-level MCP config of your client. The key names can be different in each client. |
| Claude Desktop | JSON that runs `npx -y mcp-remote@0.14.3`. The header value is in `env`, as `AUTH_HEADER`. | `claude_desktop_config.json` (Settings → Developer → Edit Config). Then quit and open Claude Desktop again. It needs Node.js. |

**Done when:** onboarding shows "Your agent called Sequential …", or the token on the **Coding agents** card shows "Used" and a time.

> **The token is shown once**
>
> Sequential shows the token only once. On **Agents** and on the **Access tokens** tab, the app says "This token is shown once. Copy it now, and treat it like a password." In onboarding, it says "The token in these snippets is shown once. Copy yours now, and treat it like a password." Sequential stores only a hash of the token. Treat the token like a password. Paste it only into your own agent. Never put it into a shared chat, a ticket or a committed file. If you lose it, revoke it and create a new one.

> **Note**
>
> **claude.ai** connects with a sign-in to Sequential, not with a token. It has its own tab in onboarding, its own card on **Agents**, and its own entry in the **Connect an agent** card. See [Connect claude.ai](/docs/connect-claude-ai).
>
> **ChatGPT** is not available yet. A line under the tabs says "ChatGPT: Not available yet." In the **Connect an agent** card, ChatGPT shows only "Not available yet." On **Agents**, the **ChatGPT** card has the badge **Not available yet** and says "We'll show the steps here when ChatGPT can connect to Sequential." If your Sequential server answers that the claude.ai sign-in is off, claude.ai also shows "Not available yet." The line under the tabs then says "claude.ai, ChatGPT: Not available yet." If Sequential could not check, claude.ai shows "Couldn't check whether claude.ai is available" and **Retry**. Press **Retry** to check again. In both cases, onboarding has no **claude.ai** tab.

### Waiting for your agent, skipping, and other ways to connect

- After **Create token**, the step shows "Waiting for your agent…". It checks every 5 seconds if the token was used, but only while the browser tab is visible.
- After 30 minutes, it stops checking and shows "No call from your agent yet." and **Check again**. **Check again** checks once, then checks for 30 more minutes.
- When the token was used and still works, the step shows "Your agent called Sequential …" and how long ago the last use was. A request that Sequential accepts with the token counts as a use. On `/mcp`, the first connection already counts. If the agent's MCP client sent its name, the step also shows "It identified itself as …". The client chooses this name. Sequential does not check it.
- The step has one button to leave. Until your agent uses the new token, the button is **Skip for now**. After that, it is **Go to dashboard**. Next to **Skip for now**, the step says "Whatever you skip waits on your dashboard." Both buttons open **Dashboard**. Neither creates a token. If you already pressed **Create token**, the token stays. Revoke it on **Agents** if you do not use it.
- If background judging is off for the project, the step says why. For example: "Background judging is switched off for this project. Your agent still sees every session's pages and errors, but new sessions come without verdicts or friction." The reasons are the same as on Watch. If Sequential cannot tell whether background judging is running, the step shows no note.
- Members and viewers see "Connecting an agent needs an admin", then "An owner or admin connects Claude and ChatGPT for this project."
- On **Setup**, **Add an agent access token to this prompt** is in the bottom bar of the **Install with your AI agent** card, next to **Copy prompt**. It creates a token with the same scopes and adds a section to the prompt: "Connect the Sequential MCP server (optional)". The section has the Claude Code command with the token. It tells any other agent to add the same URL and `Authorization` header to its user-level MCP config. Then it tells the agent to confirm the connection with one call to `list_sessions`. If the Sequential tools load only in a new session, the agent tells you to restart it and makes the call then. The same bar then says "The token in this prompt is shown once. Copy the prompt now, and treat it like a password." and "The token expires in 90 days." If you reload or leave the page, the prompt no longer has the token.
- **Dashboard** has a setup checklist that continues onboarding. See **The setup checklist on Dashboard** below.
- For the tools that an agent gets, see [Agent tools](/docs/agent-tools). For the scopes and limits, see [Limits](/docs/limits#programmatic-access).

### The setup checklist on Dashboard

**Dashboard** has a setup checklist with three steps: **Send your sessions**, **Connect your agent** and **Give it a morning**. Each step has one line that says where it stands. If Sequential cannot check a step, the line says so. It never shows this as "Not connected" or as 0. Click a step to open it. One step is open at a time.

- **When it shows.** If the dashboard has no data for the last 30 days and the project has never sent an event, every role sees the full checklist, with the title **Set up** and the project name. The page then says "Three steps, and this page fills itself." and shows no tiles. Below the checklist, a card named **What a judged session looks like** shows a sample of a judged session from a fictional shop. It is marked "Sample · not your data". It goes when the first event of the project arrives. In other cases, a smaller card, **Finish setting up**, can show below the dashboard. Owners and admins see it if no token that works has been used in the project, or if this browser showed the full checklist for the project. Members and viewers see it only while the dashboard has no data for the last 30 days, and only if this browser showed the full checklist for the project. The smaller card does not show when all three steps are done. If Sequential cannot check the project's status, the checklist does not show.
- **Send your sessions** is done when the project has an event. Until then, the step has two tabs: **Paste the snippet** and **Ask your coding agent**. From 12 October 2026, the step opens on **Ask your coding agent**. **Paste the snippet** is one click away. Viewers see "The install snippet needs a member, admin or owner — ask one for the keys." While the step is open and the browser tab is visible, it checks for the first event every 5 seconds, for 5 minutes. Then it shows **Check again**. When the first event arrives, press **Open the dashboard**.
- **Connect your agent** is done when a token that works has been used, has at least one read scope and is not a trial's token. A token with only `releases:write` does not count. Owners and admins get the same steps as in onboarding. When the step is done, its line says "Connected", the token's name and the time of its last call.
- **Give it a morning** is done when one token from step 2 has called Sequential on 3 of the last 7 days. The last 7 days are today and the 6 dates before it, in UTC. The days of different tokens do not add up. Calls to the findings tools count too. Calls to `record_release` do not count, and failed calls do not count. **Copy prompt** copies a prompt for your agent. It asks the agent to set up a task for every weekday at 08:00 in its own scheduler, and to run the task once now. Sequential does not run your agent and cannot see its scheduler. **Dashboard** counts the days once for each visit. **See each call on Agents** opens **Agents**.
- **Members and viewers** cannot do steps 2 and 3. For them, step 2 says "An agent is connected" or "No agent connected yet · an owner or admin connects agents for this project." Step 3 says "An agent calls Sequential most days" or "Not yet a regular · an owner or admin sets this up." If Sequential cannot check, the line says "Couldn't check right now." They never see token names, dates or counts.
- The card shows "N of 3 done" only when Sequential knows the state of all three steps. Members and viewers see it too when Sequential knows the state of their steps.
- **Hide** shows when step 1 is done. It hides the checklist for this project in this browser. After the checklist shows all three steps done, it does not come back for this project in this browser, also if your agent stops its calls later. If you dismissed the old "Connect your coding agent" card for a project, the checklist does not show for that project in this browser. If the browser blocks storage, a hidden checklist can come back on your next visit.

## Limits

- With only the Sequential SDK, the player header shows "anonymous", even for identified users. The previous-session and next-session buttons also stay off.
- A staging or development project records 10 % of sessions by default. See **Sampling** in its Session replay settings.
- A recording appears in **Latest** only if the same session also sent analytics events.
- The judge judges a session with at least 3 meaningful events. System events do not count. Judging starts about 30 minutes after the session's last event.
- Sequential picks up only sessions from the last 7 days for judging.
- On busy days, sessions can wait for the project's daily allowance.

## Related

- [How Sequential works](/docs/how-it-works)
- [What each SDK supports](/docs/support-matrix)
- [Feedback and calibration](/docs/feedback-and-calibration)
- [Glossary](/docs/glossary)