Creating scanners

A scanner is made up of six things you author:

1. A prompt describing what to look for.
2. A scanner type that determines the output shape – see scanner types.
3. Recording filters that select which sessions the scanner applies to.
4. A session coverage mode that pre-filters by how much happens in a recording.
5. A sampling rate that controls how many matching sessions get scanned.
6. A model, which sets what each observation costs.

You can also give a scanner its own credit limit, so it can never spend more than that in a billing period.

Ways to start

Click New scanner on the Replay Vision page. The What should the scanner find out? page offers three ways in: describe a goal, click a common starting point, or Create from scratch.

If your organization hasn't allowed AI data processing yet, an admin has to approve it before you can create a scanner. The New scanner button asks for that approval first.

Describe a goal

Type which sessions to watch and what you want to find out, for example "watch users who enter the checkout flow and summarize why they convert or drop off", then click Draft my scanner. PostHog AI reads your goal alongside your product's real pages, events, and existing scanners, then drafts the type, name, prompt, type-specific settings, and recording filters. Filters only use pages, events, and other definitions that exist in your project, so the draft doesn't invent an event name that matches nothing.

Under How much should this scanner use?, pick one:

• Free makes a free-credits-only scanner. It pauses when your organization's free monthly credits run out, so it never adds to your bill. Free isn't available once this period's free credits are used up.
• Set a budget takes a monthly budget in credits. 1,000 credits is about $10.

Either way, the draft:

• Picks the model by how much judgment the goal needs.
• Chooses a session coverage mode and the highest sampling rate the budget covers, based on recent recording volume. A free scanner is sized to your monthly free credits.
• With a budget, sets the scanner's credit limit to it, so a wrong estimate can't overspend it. A free scanner needs no limit, because it stops at your free credits.
• Can scope the scanner to an action, a cohort, or a survey when your goal names one.
• Makes an experiment scanner when your goal names a running experiment.

Start from a common question

The Common starting points list drafts a scanner from a ready-made question with one click. PostHog AI fits it to your project the same way it does a typed goal, using the spend choice you made on the left.

Review the draft

Nothing is saved until you review the draft and click Create scanner. The draft opens on an overview: what PostHog AI understood, the name, the question the scanner asks and its model, the eligible recordings with a count from recent days, and the sampling and budget. Each section has an Edit button that opens the matching editor step. Start over throws the draft away.

Create from scratch

Create from scratch opens the editor on a blank monitor. Pick the type on the Configure step. Once you save, the type is fixed.

Let the wizard write them

To start from scanners written from your codebase, run the wizard in your project directory:

It reads your codebase and creates three scanners: a breakage monitor scoped to the URLs of your key flow, a frustration monitor gated on rage clicks, and a low-sampled summarizer that uses your product's own vocabulary. The prompts name the things that actually break in your app rather than generic web copy.

These are ordinary scanners, so everything below still applies. Edit the prompt, retune the filters, or delete them.

The editor steps

Whichever way you start, the scanner editor has the steps below. A drafted scanner shows the same settings on its overview first, with an Edit button for each.

• Details – a name, a description, and tags. All three are optional, and the scanning model doesn't see the description or tags.
• Configure – the scanner type, the model, the prompt, the type's own options, and the self-driving toggle.
• Recordings – the recording filters.
• Budget – the sampling rate, session coverage, an optional scanner limit, and the estimated cost.

Editing a saved scanner uses the same steps. The type can't be changed after the scanner is created.

Writing the prompt

This is the single most important thing you'll do. A good prompt is concrete, narrow, and tells the model what to do when it's unsure. For complete worked examples, see scanner prompts.

Be concrete, not speculative

The model is good at describing what it sees. It's much less good at guessing intent or emotion from sparse evidence. Anchor the prompt in observable behavior.

✅ "Answer yes if the user scrolls a page for more than 10 seconds without clicking anything and then leaves."

❌ "Answer yes if the user feels confused."

Confusion isn't observable; rage clicks, repeated retries, and dead-end navigation are. Spell those out.

Tell it how to handle uncertainty

When the model is handed an ambiguous session, its default is to make something up. Preempt that by writing the uncertain branch into the prompt.

✅ "If there isn't enough evidence to tell, answer no."

✅ "If the session is too short to judge, tag it unclear."

Cite specific moments in reasoning

Ask for citations in the reasoning, so the result is auditable. The model is already prompted to do this, but it helps to remind it when results are vague.

✅ "Explain your verdict and cite the specific moments in the recording that drove it."

Ask for personal data only when you need it

PostHog checks every answer for personal data, such as names, email addresses, or phone numbers, that the prompt didn't ask for. An answer that still contains it after one rewrite fails with Personal data in answer, and PostHog doesn't save it. Write prompts that describe what users do, not who they are. If your scanner really needs to identify the person, say so in the prompt.

Tune iteratively against real recordings

A prompt that reads beautifully on its own can still misfire. The fastest feedback loop:

1. Author the scanner.
2. Run it on-demand against 5–10 recordings you already understand.
3. Open the observations and read the reasoning + citations.
4. Adjust the prompt where the model misread something obvious.
5. Scan another batch of recordings and repeat until the results look right.

A new scanner is enabled when you create it, and its first sweep starts within minutes. If you want to tune before the automatic sweep spends credits, turn the scanner off in the Scanners list right after creating it. On-demand scans still work while it's off, and a poorly tuned scanner can burn through your budget fast on results you'd throw away anyway.

As you read observations, answer Did the scanner get this right? with a thumbs up or down, and add a note on what it got right or wrong. PostHog turns your team's ratings into guidance the scanner applies on later scans, so rating a handful of observations improves results without editing the prompt. See improving scanners with ratings. To change the prompt itself, edit the scanner. Editing creates a new scanner version, and past observations keep the prompt that produced them.

Drafting prompts with PostHog AI

On the Configure step, Write with PostHog AI next to the prompt field opens PostHog AI with your scanner's type and current prompt. Describe what you want in natural language, and it drafts a prompt and fills it into the form for you to edit. On a scanner PostHog AI already drafted, the button reads Rewrite with PostHog AI. The button doesn't appear on every setup path for a new scanner, but it's always there when you edit a saved one.

Type-specific configuration

Each scanner type has a few extra knobs. The full reference is on the scanner types page; the highlights:

• Classifier – define your Categories, choose whether multiple categories per session are allowed, and whether the model can invent categories outside your list. Suggest categories with PostHog AI suggests categories grounded in your prompt, your product, and what's been seen in recordings. On a scanner PostHog AI already drafted, the button reads Suggest more categories. Like Write with PostHog AI, it doesn't appear on every setup path for a new scanner.
• Scorer – set the numeric scale (min, max) and an optional one-word score label.
• Summarizer – pick a summary length (short / medium / long). The core summarizer prompt is built in, so the prompt field becomes Additional context: use it for product context or steering, like what the ideal user flow looks like.
• Monitor – turn on Allow inconclusive verdicts to let the model answer inconclusive rather than forcing a yes/no answer.

The editor also has a model picker, which sets the price of every observation the scanner makes: 2 credits on Gemini 3.5 Flash Lite, 5 on Gemini 3 Flash (the default), and 15 on Gemini 3.8 Flash. Newer models tend to produce higher-quality observations, but the top tier costs over seven times as much per session as the cheapest. Start on the default. If results are close but not quite right, tune the prompt before reaching for a pricier model, since a sharper prompt is free and rating a few new observations will tell you whether it worked. See quota and limits for how credits are metered.

Filters: scoping the scanner

The Recordings step uses the same filter builder as the Session Replay recordings list. You can filter by:

• Events and actions the session contains, and event properties
• Person properties (e.g. plan tier, signup date)
• Session properties (e.g. page count, country)
• Group properties (e.g. company name, account tier) – requires group analytics
• Cohorts
• Feature flags
• Recording duration

Choose whether a session has to match all of your filters or any of them, and turn on Filter out internal and test users to apply your project's internal and test account filters.

A scanner with no filters matches every eligible session in your project, and the editor warns you about this. It also warns you when no recordings from recent days match your filters, because the scanner would have nothing to scan. A scanner with narrow filters – e.g. "sessions on /checkout longer than 30 seconds for users on the trial plan" – is much cheaper, much faster to iterate on, and usually more useful.

One limit applies regardless of filters: recordings with more than 1 hour of active interaction take too long to analyze well, so Vision always skips them.

To watch the sessions of an experiment, create an experiment scanner. It adds each session's variant and lets you compare what users do in each variant.

A good default discipline: start with a narrow filter while you're tuning the prompt, then widen the filter once you trust the results.

Session coverage: filtering by activity

The Session coverage setting on the Budget step pre-filters recordings by their activity level before sampling is applied. It uses an activity score that estimates how much happens in a recording – interactions, errors, navigation – versus idle or empty sessions.

A scanner you set up in the editor starts on Medium and high activity recordings. Sessions that don't have an activity score yet are treated as average and kept by every mode.

Keep All recordings when your scanner looks for quiet behavior, such as people giving up or drifting away. Those sessions look uneventful, so a tighter mode would skip the very sessions the scanner is looking for.

The three-step filtering process is:

1. Recording filters pick sessions matching your criteria.
2. Session coverage drops low-activity sessions by activity score.
3. Sampling rate randomly keeps a fraction of what's left.

Use a tighter coverage mode when you want to spend your budget on sessions where something actually happened, rather than idle or empty recordings.

Sampling rate: controlling volume

The sampling rate (0.1–100%) is applied after the filters and session coverage. A scanner with filter "sessions over 30 seconds" and sampling 25% scans roughly one in four of those sessions.

The Budget step shows an Estimated cost – the credits the scanner is projected to spend per month at the selected model's price, next to what you've spent this billing period, what your other scanners and backfills are projected to spend, and your spend limit. It's based on your project's recent recording volume, the filters you've set, the session coverage mode, the sampling rate, and the model. Use this to size the scanner against your budget before saving.

If the estimate looks too high, you have four knobs:

• Narrow the filters.
• Tighten the session coverage mode (All recordings → Medium and high activity recordings → High activity recordings only).
• Lower the sampling rate.
• Pick a cheaper model.

Scanner limit: capping one scanner

Turn on Scanner limit on the Budget step to cap what this scanner can spend in a billing period, on top of your organization's limit. Enter the limit in Credits, or select Observations to enter a number of observations. The editor converts an observation count to credits at the selected model's price. When the scanner reaches its limit, it stops scanning until the next billing period. It stays enabled, but the sessions it skipped aren't scanned later, even if you raise the limit. The editor warns you when the limit is below the scanner's estimated monthly cost, or too low to pay for a single scan.

Above it, Free credits only keeps the scanner to your organization's free monthly credits, so it never adds to your bill. It pauses when they run out and starts again when the billing period resets. See free credits only.

Enabling and disabling

Scanners are enabled by default when you save. A new scanner's first sweep scans a few matching recordings from the last 24 hours, so you see results quickly. After that, an enabled scanner sweeps for new matching sessions every few minutes. It doesn't go back through older recordings on its own – use Backfill a date range on the scanner's Run tab for that. See running scanners.

Turn a scanner on or off with its switch in the Scanners list or on the Usage tab. Disabling stops the background sweep. On-demand triggers (from the player, the scanner's Run tab, or via MCP) still work on a disabled scanner – disabling only affects the automatic schedule.

To stop a scanner entirely, delete it. Deleting a scanner also removes all of its observations from the Observations tab. The $recording_observed events the scanner produced are ordinary PostHog events in your project's event stream and aren't affected – they stay queryable.

Handing off to Responder agents

Each scanner has an Emit findings as Signals toggle on the Self-driving card of the editor's Configure step. When enabled, the scanner gains a side mission: during each scan, the model looks for clear, actionable product issues – bugs, crashes, design flaws, or significant UX friction – and reports them as findings.

The scanner's primary task (monitoring, classifying, scoring, or summarizing) is unaffected. The side mission runs alongside it, and most scans produce no finding at all. The bar is deliberately high: a finding must be self-contained and concrete enough for someone with no session context to act on it.

Findings are emitted as signals to the self-driving inbox, where Responder agents can pick them up, research the issue against your codebase and product data, and potentially open a PR.

The toggle is the only setup required – there's no additional configuration in PostHog Desktop Inbox for this source. Once a scanner has emitted signals, the card shows how many it has emitted and how many reports and PRs they contributed to.