creating-replay-vision-scanners

Pick a scanner_type and write its scanner_config. Every type needs a prompt; the rest is type-specific:

scanner_type is locked after creation — to change it you delete and recreate, so confirm the type is right up front, and get the scanner_config shape right (a wrong shape is a create error, not a silent default — unknown keys are rejected too).

If the user's intent makes the type and prompt obvious, just proceed — don't interrogate them.

The query is a RecordingsQuery shape that selects which recordings the scanner watches. date_from and date_to are ignored (the schedule controls time), so don't bother setting them. Narrow the query to the sessions that actually matter — by event, URL, person property, duration, etc. A narrow query is the single biggest lever on cost.

When the target is one experiment's exposed population, that's its own job — use the scanning-experiments-with-replay-vision skill, which derives this query from the experiment's exposure criteria instead of hand-building it.

Two levers narrow it further, applied in this order:

• sampling_mode (default comprehensive) is a quality pre-filter on the matched sessions: focused keeps only the top sessions by surfacing score, balanced drops the lowest-quality ones, comprehensive keeps everything. Use it to spend the budget on sessions worth watching rather than shrinking coverage at random.
• sampling_rate (0..1, default 1.0) is a random downsample applied after that. Lower it to trade coverage for budget. Exactly 0 pauses scanning; non-zero rates below 0.0001 are rejected.

model sets the price of every observation the scanner makes, so it's a cost lever as much as a quality one: gemini-3.5-flash-lite (2 credits), gemini-3-flash-preview (5 credits, the default) and gemini-3.8-flash (15 credits). Start at the default and only reach for gemini-3.8-flash when the cheaper tiers demonstrably miss what the scanner is looking for.

Before creating, run both checks and reason about them together:

1. Estimate spend — call vision-scanners-estimate-create with the proposed query, sampling_rate, sampling_mode and model. It returns matched_sessions_in_window, the window_days measured, estimated_observations_per_month, credits_per_observation, estimated_credits_per_month, and other_enabled_scanners_monthly_credits (what the org's other enabled scanners are already projected to spend). When editing an existing scanner, pass its scanner_id so its own estimate isn't counted twice.
2. Check budget — call vision-quota-retrieve for remaining and exhausted against the org's credit_limit (credits, 1 credit = $0.01; null when uncapped), plus the period_start/period_end of the current period.

Compare credits with credits over the same horizon, the way the product UI does — remaining is denominated in credits, not observations, so comparing it against estimated_observations_per_month understates the cost by the model's per-observation price. remaining is what's left for the rest of the current period, so prorate the monthly projection to that window rather than comparing a full month against it:

fleet_monthly    = estimated_credits_per_month + other_enabled_scanners_monthly_credits
period_days      = period_end - period_start        (in days)
days_left        = period_end - now                 (in days, floored at 0)
rest_of_period   = fleet_monthly * days_left / period_days

Then decide on rest_of_period against remaining:

• If it comfortably fits within remaining, proceed.
• If it's a large fraction of (or exceeds) remaining, stop and tell the user the concrete numbers (e.g. "This scanner is projected to spend ~X credits/month, about $Y; over the N days left this period that's ~R credits against the Z you have left."), then confirm before creating. Tightening the query, switching sampling_mode to focused, lowering sampling_rate, or picking a cheaper model are all ways to bring it down.
• Quote estimated_credits_per_month too, since it's what the scanner costs in a full period once this one resets. Mid-period a scanner can fit in remaining and still blow the next period's budget.
• If the org is already exhausted, say so. A new enabled scanner won't produce anything until the budget resets: its scheduled observations are silently skipped, and on-demand scans are rejected outright.
• If the estimate is a large fraction of remaining but the user still wants the scanner, offer a per-scanner cap: set credit_limit on create so this scanner can only ever spend that many credits per billing period. It stops scanning once the credits left can't cover another observation, then resumes when the period resets. Sessions it skipped while capped are not scanned later.

Confirmation here is a conversation step, not an API capability — surface the trade-off and let the user choose. When the projected volume is clearly small relative to the budget, you don't need to ask.

Call vision-scanners-create. Minimal example:

{
  "name": "Rage click monitor",
  "scanner_type": "monitor",
  "scanner_config": { "prompt": "Flag sessions where the user repeatedly clicks the same element in frustration." },
  "query": { "kind": "RecordingsQuery", "events": [{ "id": "$rageclick", "type": "events" }] },
  "sampling_rate": 1.0,
  "sampling_mode": "comprehensive",
  "model": "gemini-3-flash-preview",
  "enabled": true
}

name must be unique within the team. Set enabled: false if the user wants to create it paused (no schedule, no quota consumption) and turn it on later.

emits_signals: true is the other switch worth knowing: it augments the prompt with the Signals side mission and pushes one signal per finding into the PostHog Signals inbox, where findings corroborate across sessions into reports. Turn it on when the user wants the scanner to feed their inbox rather than just accumulate observations they have to go read.