# How Sequential works

> Your SDK sends events. Sequential links them to the session replay by session id. About half an hour after a session ends, the AI judge reads them.

> **In short**
>
> - Your existing SDK sends events to Sequential. You do not add a second analytics SDK.
> - Sequential gives each event one of nine classes and stores it.
> - The recording and the events share a session id. Your events show on the replay timeline.
> - About 30 minutes after a session's last event, the judge reads its events against your rubric.
> - The judge reads events, not the video. Custom events tell it which moments matter.

## From event to verdict

1. **Your SDK sends events.** Each event carries a key that names your project.
2. **Sequential classifies and stores each event.** Each event keeps the name your SDK gave it. It also gets one of nine classes, such as Page view, Click or Custom.
3. **The recorder uploads the recording.** This step is optional.
4. **The events and the recording share a session id.** Matching ids put your events on the replay timeline.
5. **The judge reads the session's events.** The judge starts when a session has no new events for 30 minutes. The session must have at least 3 meaningful events.
6. **The analytics pages query the events directly.** The judge does not take part. These pages are **Events**, **Funnels**, **Flows**, **Retention**, **Users**, **Accounts** and Sessions → **Latest**.

### Which SDKs and keys Sequential accepts

- Sequential accepts PostHog, Mixpanel, Amplitude, Pendo, the Smartlook compatibility script and Sequential's own SDK.
- Each SDK sends its events in its own format.
- The key is the project's ingest key. For Pendo, the key is your own Pendo API key.
- Sequential accepts only browser SDKs and PostHog's mobile SDKs.
- Sequential rejects server-side SDKs and HTTP libraries as bot traffic. Examples: posthog-node, curl, axios.

See [What each SDK supports](/docs/support-matrix).

### How Sequential classifies events

- The nine classes include Page view, Click, Error, Custom and System.
- If Sequential has no rule for a name, the event becomes Custom. This includes your own events and vendor events that Sequential does not list. For example: PostHog mobile's `Application Opened`.
- Known vendor housekeeping events become System. For example: page-leave and web-vitals events.
- Sequential stores System events but hides them from event lists by default.

See [Events](/docs/events).

### How the recorder starts and shares the session id

- The recorder reads your project's recording settings before it starts.
- On the web, Sequential's own SDK and the Smartlook compatibility script start the recorder for you. They do this when session replay is on for the project.
- With PostHog, Mixpanel, Amplitude or Pendo, the recorder is a separate script tag next to your analytics SDK.
- On mobile, the supported SDK uploads its own recording. See [Mobile apps](/docs/mobile).
- The recorder uses your analytics SDK's session id. Sequential's own SDK gives its id to the recorder automatically.
- If the SDK has no session id, the recorder creates one. The recorder registers it with PostHog, Mixpanel or Pendo, so their events carry it too.
- Matching ids put your events on the replay timeline and in the player's **Events** tab. See [Sessions](/docs/sessions).

### What the judge returns

- Sequential sends a short text digest of the session's events, with your rubric, to the judge.
- The judge answers each question with probabilities. Sequential stores these numbers.
- Sequential assembles the sentences you read later from these numbers. The judge writes no prose.

See [Judgments](/docs/judgments).

## Where you see the results

| Where | What it does | When it judges |
|---|---|---|
| Sessions → **Watch** | Ranks judged sessions, the most urgent first. | In the background, usually 30–35 minutes after the session's last event. |
| Sessions → **Ask** | Judges candidate sessions' events against a plain-language description you write. | When you run a search. |
| **Insights** tab in the replay player | Judges the open recording. | When you open the tab. If the recording is not ready yet, when the open player loads it. |

### Watch buttons

- If a session has a recording and the judge found a key moment, **Watch from m:ss** opens the replay there.
- A recorded session without a key moment offers **Open replay**.
- To check a verdict, open the replay.

### How long each step takes

| Step | When |
|---|---|
| Events on the analytics pages | Within about a minute. Sequential stores events in batches, and your SDK also batches them. |
| A replay you can play | A few minutes after the last upload of the session arrives, up to about 6. While the session is still going, you usually cannot play it yet. |
| A verdict in **Watch** | Usually 30–35 minutes after the session's last event. |
| **Ask** and **Insights** | When you run the search or open the tab. |

- Sequential's SDK sends each event within 5 seconds.
- The recorder uploads as it goes. Sequential prepares the uploads in 5-minute periods. You can play a recording only when all its uploads are ready. Until then, the player shows the time when the recording will be ready, and opens it on its own.
- A verdict in **Watch** comes no sooner than 30 minutes after the session's last event.
- Sequential checks for sessions every 5 minutes. So the verdict usually comes 30–35 minutes after the last event.
- A verdict takes longer when many sessions wait in the queue. It also takes longer when today's allowance is used up.

## Why the events matter more than the recording

The background judge never watches the video. It reads a digest of your stored events.

- **A session without events gets no verdict.** The judge does not read a session that has a recording but no analytics events. Sessions → **Latest** does not list it, and **Ask** cannot find it.
- **Sequential judges sessions that have no recording.** It ranks them as normal. Their **Watch** row shows **No recording** and offers **Open events**.
- **Custom events name your milestones.** A custom event such as `checkout_completed` gives the judge a named milestone. Without custom events, it sees only generic activity.

### What the digest contains

- The judge sees page paths, click text, form submits, error messages and your custom events. Each custom event comes with a short summary of its properties.
- The judge compares the outcome with your named milestones. Without custom events, nothing tells it which step of your product mattered. See [Send custom events](/docs/custom-events).
- The digest carries page paths without hosts or query strings. It reduces any other full web address to its path.
- The digest shortens labels.
- The digest includes no user id.
- The digest drops custom-event properties with personal-looking names, such as email or phone. See [AI and third parties](/docs/ai-and-third-parties).
- From the recording, the background judge takes only three counts that DevTools measured: JS errors, failed requests and console errors.
- If DevTools did not measure a count, the digest leaves it out. Sequential never sends a missing count as zero. See [DevTools in replays](/docs/devtools).
- In a very long session, the digest can leave out late custom events. See **Limits**.

## What it needs

- Events with a session id, from a supported SDK. See [Install Sequential](/docs/install).
- For replays on the web with PostHog, Mixpanel, Amplitude or Pendo: the recorder tag. See [Session replay (web)](/docs/session-replay).
- Named custom events for the moments that matter in your product. See [Send custom events](/docs/custom-events).
- Background judging on for the project. **Watch** needs it. It is on by default, and your Sequential server must also allow it.

> **Where to turn background judging on or off**
>
> Owners and admins use the switch **Judge new sessions automatically** under **Settings** → **Projects** → your project → **Insights**. If **Watch** says that background judging is off for every project on the server, or that the server has no AI key, ask the person who runs your Sequential server. When the server has no AI key, the switch reads "(paused)" after **On** or **Off**, and you cannot change it. The note under it starts with **Paused.**

## Limits

- **The judge reads each session once.** The judge does not see events that arrive after the judgment.
- **A rubric change does not re-judge old sessions.** It applies only to sessions judged from then on. Earlier sessions are marked "judged with an earlier rubric".
- **Old sessions are not judged.** Judging looks back 7 days. When background judging is turned on, Sequential does not judge sessions that ended before that.
- **Short sessions are skipped.** Sequential marks a session with fewer than 3 meaningful events as too short. System events do not count. The judge never reads the session.
- **Ask shows likely matches only.** An empty or short result does not mean that nothing like it happened.
- **Sequential shortens very long sessions.** The judge reads at most 255 events per session, so it can miss a late milestone.
- **Ids must match exactly.** If your SDK and the recorder report different session ids, the replay loses its event markers. The judge never reads events without a session id. **Ask** cannot find them.
- **A sampled project records only some sessions.** New staging and development projects record 10% of sessions by default.
- **Server-side SDKs are rejected.** Sequential treats events from posthog-node, curl or axios as bot traffic and rejects them.
- **Judging stops when the daily allowance is used up.** Background judging has its own allowance. **Ask** in the app and **Ask** from an agent each have a separate one ([Limits](/docs/limits)). Background judging waits for the reset at midnight UTC.
- **A failed judgment is not retried.** If judging fails for a lasting reason, Sequential marks the session failed. That session never gets a verdict.
- **Insights and Watch can disagree.** **Insights** also reads the recording. Re-running **Insights** does not change the verdict that **Watch** shows.

### Exact limit behaviours

| Limit | What happens |
|---|---|
| Lasting failures | If judging fails for a lasting reason, Sequential marks the session failed and does not try it again. For example: the session is still too large after Sequential shortens it. |
| Throughput | Each check picks up at most 500 sessions per project. Each project has a daily allowance for background judging. **Ask** does not use it. |
| Daily allowance | When the allowance is used up, background judging waits for the reset at midnight UTC. Sequential retries waiting sessions hourly, so judging can resume up to an hour after the reset. |
| Ask | Each run judges up to 200 sessions from the newest 2,000 in your date range. It leaves out sessions that the judge rated unlikely to match. |
| Shortening | The judge leaves out clicks first, then custom events. It keeps the earliest events of each kind. |
| Insights | The **Insights** tab has its own daily allowance. **Re-run** forces a fresh judgment at most once every 10 minutes per session. If you press it again sooner, the tab shows the saved verdict. |
| Insights and Watch can differ | The **Insights** digest also uses the recording, so its verdict can differ from the **Watch** row's. Re-running **Insights** never changes the stored verdict. |
| Sampling | See your project's rate under Settings → Projects → your project → **Session replay** → **Sampling**. See [Recording settings](/docs/recording-settings). |

## Related

- [What is Sequential](/docs/what-is-sequential)
- [Your first hour](/docs/quickstart)
- [Sessions](/docs/sessions)
- [Judgments](/docs/judgments)
- [Watch: sessions worth your time](/docs/watch)
- [Ask: find sessions by describing them](/docs/ask)
- [Session insights](/docs/session-insights)
- [Reading a verdict](/docs/reading-verdicts)
- [Customise the rubric](/docs/rubric)
- [Limits](/docs/limits)