Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(mcp): give replay vision scanner tools a compact recording filter schema (#125746)

Kim Svatos Dugan8c8bc1bb127d
diff --git a/products/replay_vision/backend/queries/scanner_volume_estimate.py b/products/replay_vision/backend/queries/scanner_volume_estimate.py
index a22b42a317af..39d7e5727eeb 100644
--- a/products/replay_vision/backend/queries/scanner_volume_estimate.py
+++ b/products/replay_vision/backend/queries/scanner_volume_estimate.py
@@ -105,6 +105,11 @@ class MatchCheckIncomplete(Exception):
"""The match check could not reach an answer: every fetched recording was excluded and more remain."""
+def _combines_with_or(query: RecordingsQuery) -> bool:
+ # Read the way the recordings query builder reads it: every operand but AND, an explicit null included, is OR.
+ return query.operand != FilterLogicalOperator.AND_
+
+
def has_recent_matching_recording(
*,
team: Team,
@@ -134,7 +139,7 @@ def has_recent_matching_recording(
raise TimeoutError("The recent-recording match check ran out of time.")
return remaining
- scan_window_days = budget.window_days(unsampled=query.operand == FilterLogicalOperator.OR_)
+ scan_window_days = budget.window_days(unsampled=_combines_with_or(query))
windowed = query.model_copy(deep=True)
windowed.date_from = (dt.datetime.now(dt.UTC) - dt.timedelta(days=scan_window_days)).isoformat()
windowed.date_to = None
@@ -197,7 +202,7 @@ def estimate_scanner_session_volume(
# Sampling is only sound when every match must pass the sampled events leg; under OR, sessions
# matched via unsampled branches (persons, cohorts, console logs) would be multiplied by the
# correction. Without sampling the scan is full price, so bound its window instead.
- unsampled = query.operand == FilterLogicalOperator.OR_
+ unsampled = _combines_with_or(query)
sample_factor = None if unsampled else _ESTIMATE_EVENTS_SAMPLE_FACTOR
scan_window_days = budget.window_days(unsampled=unsampled)
diff --git a/products/replay_vision/backend/tests/test_scanner_candidate_query.py b/products/replay_vision/backend/tests/test_scanner_candidate_query.py
index 6f8b76e03ad4..96d9a403f1e1 100644
--- a/products/replay_vision/backend/tests/test_scanner_candidate_query.py
+++ b/products/replay_vision/backend/tests/test_scanner_candidate_query.py
@@ -511,8 +511,9 @@ class TestScannerCandidateQueryAgainstClickHouse(ClickhouseTestMixin):
assert estimate.matched_sessions == 1
+ @pytest.mark.parametrize("operand", [FilterLogicalOperator.OR_, None])
@pytest.mark.django_db
- def test_unsampled_estimate_window_narrows_only_for_previews(self, team) -> None:
+ def test_unsampled_estimate_window_narrows_only_for_previews(self, team, operand) -> None:
# An OR operand rules out the events SAMPLE, so a preview scans a shorter window instead of
# paying full price. A persisted estimate keeps the whole week, because a partial week
# inherits whichever weekdays it covered and biases the monthly projection.
@@ -525,8 +526,9 @@ class TestScannerCandidateQueryAgainstClickHouse(ClickhouseTestMixin):
timestamp=first,
properties={"$session_id": "older-match"},
)
+ # The query builder reads a null operand as OR too, so the estimate must not sample it.
query = RecordingsQuery(
- operand=FilterLogicalOperator.OR_,
+ operand=operand,
events=[{"id": "$pageview", "type": "events", "order": 0, "name": "$pageview"}],
)
diff --git a/products/replay_vision/mcp/tools.yaml b/products/replay_vision/mcp/tools.yaml
index b42f1f47f784..b5b74c1be40a 100644
--- a/products/replay_vision/mcp/tools.yaml
+++ b/products/replay_vision/mcp/tools.yaml
@@ -608,12 +608,16 @@ tools:
`_posthogUrl` opens the scanner where they do it. There is nothing to rate yet, so this is a closing
sentence for them, not a step for you.
exclude_params:
+ - query
- id
- scanner_version
- last_swept_at
- created_at
- created_by
- updated_at
+ param_overrides:
+ query:
+ input_schema: ScannerRecordingsFilterSchema
requires_ai_consent: true
vision-scanners-dashboard-create:
operation: vision_scanners_create_dashboard_create
@@ -703,17 +707,23 @@ tools:
title: Estimate replay vision scanner volume
description: >
Preview how many observations a proposed scanner would generate, and what they would cost, before saving it.
- Send a `query` (`RecordingsQuery` shape; `date_from`/`date_to` are ignored — the estimate uses a fixed
- 30-day lookback) plus the proposed `sampling_rate`, `sampling_mode` and `model`, and `scanner_id` when
- re-estimating an existing scanner so its own projection isn't double-counted. For an experiment scanner,
- pass `experiment` with the same `experiment_id` and `variants` you will save, so the estimate counts only
- exposed sessions. Returns `matched_sessions_in_window`, the `window_days` it was measured over,
- `estimated_observations_per_month`, `credits_per_observation`, `estimated_credits_per_month`, and
- `other_enabled_scanners_monthly_credits` (the org's other enabled scanners' projected spend). Enabled
- scanners sweep every 5 minutes, so a broad query can exhaust the budget quickly — run this before
- `vision-scanners-create` and compare the *credit* figures (never raw observation counts) against `remaining`
- from `vision-quota-get`. These projections are per month while `remaining` covers only the rest of the
- current period, so prorate them by the days left between `period_start` and `period_end` before comparing.
+ Send a `query` (`RecordingsQuery` shape; `date_from`/`date_to` are ignored, because the estimate counts a
+ recent window, `window_days` in the response, and scales it to 30 days) plus the proposed `sampling_rate`,
+ `sampling_mode` and `model`, and `scanner_id` when re-estimating an existing scanner so its own projection
+ isn't double-counted. For an experiment scanner, pass `experiment` with the same `experiment_id` and
+ `variants` you will save, so the estimate counts only exposed sessions. Returns
+ `matched_sessions_in_window`, the `window_days` it was measured over, `estimated_observations_per_month`,
+ `credits_per_observation`, `estimated_credits_per_month`, and `other_enabled_scanners_monthly_credits` (the
+ org's other enabled scanners' projected spend). Enabled scanners sweep every 5 minutes, so a broad query can
+ exhaust the budget quickly — run this before `vision-scanners-create` and compare the *credit* figures
+ (never raw observation counts) against `remaining` from `vision-quota-get`. These projections are per month
+ while `remaining` covers only the rest of the current period, so prorate them by the days left between
+ `period_start` and `period_end` before comparing.
+ exclude_params:
+ - query
+ param_overrides:
+ query:
+ input_schema: ScannerEstimateRecordingsFilterSchema
vision-scanners-get:
operation: vision_scanners_retrieve
enabled: true
@@ -1071,21 +1081,26 @@ tools:
idempotent: true
title: Update replay vision scanner
description: >
- Partially update a replay vision scanner by ID. Send only the fields you want to change. Common changes:
- toggle `enabled` to pause/resume scanning, adjust `sampling_rate` or `sampling_mode`, tweak the
- `scanner_config` prompt or tags, or refine the `query` to watch a different slice of sessions.
- `scanner_type` is locked after creation — to change it, delete and recreate. Editing any config field bumps
- `scanner_version`; existing observations keep a snapshot of the previous config for reproducibility. If you
- widen the `query`, raise `sampling_rate`, loosen `sampling_mode`, or move to a pricier `model`, re-check
- projected spend with `vision-scanners-estimate` and remaining budget with `vision-quota-get` first — the
- scanner resumes sweeping every 5 minutes at the new, broader scope.
+ Partially update a replay vision scanner by ID. Send only the fields you want to change, except `query`: it
+ replaces the stored filter as a whole, so read it with `vision-scanners-get` and send it back in full with
+ your changes. Common changes: toggle `enabled` to pause/resume scanning, adjust `sampling_rate` or
+ `sampling_mode`, tweak the `scanner_config` prompt or tags, or refine the `query` to watch a different slice
+ of sessions. `scanner_type` is locked after creation — to change it, delete and recreate. Editing any config
+ field bumps `scanner_version`; existing observations keep a snapshot of the previous config for
+ reproducibility. If you widen the `query`, raise `sampling_rate`, loosen `sampling_mode`, or move to a
+ pricier `model`, re-check projected spend with `vision-scanners-estimate` and remaining budget with
+ `vision-quota-get` first — the scanner resumes sweeping every 5 minutes at the new, broader scope.
exclude_params:
+ - query
- id
- scanner_version
- last_swept_at
- created_at
- created_by
- updated_at
+ param_overrides:
+ query:
+ input_schema: ScannerUpdateRecordingsFilterSchema
requires_ai_consent: true
vision-scanners-variants-list:
operation: vision_scanners_variants_list
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 2f4a2fe65868..b7a537f2cd6c 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -15813,7 +15813,7 @@
"requires_ai_consent": true
},
"vision-scanners-estimate": {
- "description": "Preview how many observations a proposed scanner would generate, and what they would cost, before saving it. Send a `query` (`RecordingsQuery` shape; `date_from`/`date_to` are ignored — the estimate uses a fixed 30-day lookback) plus the proposed `sampling_rate`, `sampling_mode` and `model`, and `scanner_id` when re-estimating an existing scanner so its own projection isn't double-counted. For an experiment scanner, pass `experiment` with the same `experiment_id` and `variants` you will save, so the estimate counts only exposed sessions. Returns `matched_sessions_in_window`, the `window_days` it was measured over, `estimated_observations_per_month`, `credits_per_observation`, `estimated_credits_per_month`, and `other_enabled_scanners_monthly_credits` (the org's other enabled scanners' projected spend). Enabled scanners sweep every 5 minutes, so a broad query can exhaust the budget quickly — run this before `vision-scanners-create` and compare the *credit* figures (never raw observation counts) against `remaining` from `vision-quota-get`. These projections are per month while `remaining` covers only the rest of the current period, so prorate them by the days left between `period_start` and `period_end` before comparing.",
+ "description": "Preview how many observations a proposed scanner would generate, and what they would cost, before saving it. Send a `query` (`RecordingsQuery` shape; `date_from`/`date_to` are ignored, because the estimate counts a recent window, `window_days` in the response, and scales it to 30 days) plus the proposed `sampling_rate`, `sampling_mode` and `model`, and `scanner_id` when re-estimating an existing scanner so its own projection isn't double-counted. For an experiment scanner, pass `experiment` with the same `experiment_id` and `variants` you will save, so the estimate counts only exposed sessions. Returns `matched_sessions_in_window`, the `window_days` it was measured over, `estimated_observations_per_month`, `credits_per_observation`, `estimated_credits_per_month`, and `other_enabled_scanners_monthly_credits` (the org's other enabled scanners' projected spend). Enabled scanners sweep every 5 minutes, so a broad query can exhaust the budget quickly — run this before `vision-scanners-create` and compare the *credit* figures (never raw observation counts) against `remaining` from `vision-quota-get`. These projections are per month while `remaining` covers only the rest of the current period, so prorate them by the days left between `period_start` and `period_end` before comparing.",
"category": "Replay vision",
"feature": "replay_vision",
"summary": "Estimate replay vision scanner volume",
@@ -16057,7 +16057,7 @@
}
},
"vision-scanners-update": {
- "description": "Partially update a replay vision scanner by ID. Send only the fields you want to change. Common changes: toggle `enabled` to pause/resume scanning, adjust `sampling_rate` or `sampling_mode`, tweak the `scanner_config` prompt or tags, or refine the `query` to watch a different slice of sessions. `scanner_type` is locked after creation — to change it, delete and recreate. Editing any config field bumps `scanner_version`; existing observations keep a snapshot of the previous config for reproducibility. If you widen the `query`, raise `sampling_rate`, loosen `sampling_mode`, or move to a pricier `model`, re-check projected spend with `vision-scanners-estimate` and remaining budget with `vision-quota-get` first — the scanner resumes sweeping every 5 minutes at the new, broader scope.",
+ "description": "Partially update a replay vision scanner by ID. Send only the fields you want to change, except `query`: it replaces the stored filter as a whole, so read it with `vision-scanners-get` and send it back in full with your changes. Common changes: toggle `enabled` to pause/resume scanning, adjust `sampling_rate` or `sampling_mode`, tweak the `scanner_config` prompt or tags, or refine the `query` to watch a different slice of sessions. `scanner_type` is locked after creation — to change it, delete and recreate. Editing any config field bumps `scanner_version`; existing observations keep a snapshot of the previous config for reproducibility. If you widen the `query`, raise `sampling_rate`, loosen `sampling_mode`, or move to a pricier `model`, re-check projected spend with `vision-scanners-estimate` and remaining budget with `vision-quota-get` first — the scanner resumes sweeping every 5 minutes at the new, broader scope.",
"category": "Replay vision",
"feature": "replay_vision",
"summary": "Update replay vision scanner",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 1995b7533e68..fdcab781c8c5 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -16587,7 +16587,7 @@
"requires_ai_consent": true
},
"vision-scanners-estimate": {
- "description": "Preview how many observations a proposed scanner would generate, and what they would cost, before saving it. Send a `query` (`RecordingsQuery` shape; `date_from`/`date_to` are ignored — the estimate uses a fixed 30-day lookback) plus the proposed `sampling_rate`, `sampling_mode` and `model`, and `scanner_id` when re-estimating an existing scanner so its own projection isn't double-counted. For an experiment scanner, pass `experiment` with the same `experiment_id` and `variants` you will save, so the estimate counts only exposed sessions. Returns `matched_sessions_in_window`, the `window_days` it was measured over, `estimated_observations_per_month`, `credits_per_observation`, `estimated_credits_per_month`, and `other_enabled_scanners_monthly_credits` (the org's other enabled scanners' projected spend). Enabled scanners sweep every 5 minutes, so a broad query can exhaust the budget quickly — run this before `vision-scanners-create` and compare the *credit* figures (never raw observation counts) against `remaining` from `vision-quota-get`. These projections are per month while `remaining` covers only the rest of the current period, so prorate them by the days left between `period_start` and `period_end` before comparing.",
+ "description": "Preview how many observations a proposed scanner would generate, and what they would cost, before saving it. Send a `query` (`RecordingsQuery` shape; `date_from`/`date_to` are ignored, because the estimate counts a recent window, `window_days` in the response, and scales it to 30 days) plus the proposed `sampling_rate`, `sampling_mode` and `model`, and `scanner_id` when re-estimating an existing scanner so its own projection isn't double-counted. For an experiment scanner, pass `experiment` with the same `experiment_id` and `variants` you will save, so the estimate counts only exposed sessions. Returns `matched_sessions_in_window`, the `window_days` it was measured over, `estimated_observations_per_month`, `credits_per_observation`, `estimated_credits_per_month`, and `other_enabled_scanners_monthly_credits` (the org's other enabled scanners' projected spend). Enabled scanners sweep every 5 minutes, so a broad query can exhaust the budget quickly — run this before `vision-scanners-create` and compare the *credit* figures (never raw observation counts) against `remaining` from `vision-quota-get`. These projections are per month while `remaining` covers only the rest of the current period, so prorate them by the days left between `period_start` and `period_end` before comparing.",
"category": "Replay vision",
"feature": "replay_vision",
"summary": "Estimate replay vision scanner volume",
@@ -16831,7 +16831,7 @@
}
},
"vision-scanners-update": {
- "description": "Partially update a replay vision scanner by ID. Send only the fields you want to change. Common changes: toggle `enabled` to pause/resume scanning, adjust `sampling_rate` or `sampling_mode`, tweak the `scanner_config` prompt or tags, or refine the `query` to watch a different slice of sessions. `scanner_type` is locked after creation — to change it, delete and recreate. Editing any config field bumps `scanner_version`; existing observations keep a snapshot of the previous config for reproducibility. If you widen the `query`, raise `sampling_rate`, loosen `sampling_mode`, or move to a pricier `model`, re-check projected spend with `vision-scanners-estimate` and remaining budget with `vision-quota-get` first — the scanner resumes sweeping every 5 minutes at the new, broader scope.",
+ "description": "Partially update a replay vision scanner by ID. Send only the fields you want to change, except `query`: it replaces the stored filter as a whole, so read it with `vision-scanners-get` and send it back in full with your changes. Common changes: toggle `enabled` to pause/resume scanning, adjust `sampling_rate` or `sampling_mode`, tweak the `scanner_config` prompt or tags, or refine the `query` to watch a different slice of sessions. `scanner_type` is locked after creation — to change it, delete and recreate. Editing any config field bumps `scanner_version`; existing observations keep a snapshot of the previous config for reproducibility. If you widen the `query`, raise `sampling_rate`, loosen `sampling_mode`, or move to a pricier `model`, re-check projected spend with `vision-scanners-estimate` and remaining budget with `vision-quota-get` first — the scanner resumes sweeping every 5 minutes at the new, broader scope.",
"category": "Replay vision",
"feature": "replay_vision",
"summary": "Update replay vision scanner",
diff --git a/services/mcp/schema/tool-inputs.json b/services/mcp/schema/tool-inputs.json
index 9909f186b798..7fda6a07eacc 100644
--- a/services/mcp/schema/tool-inputs.json
+++ b/services/mcp/schema/tool-inputs.json
@@ -1836,6 +1836,381 @@
},
"description": "The complete desired set of shared (saved) metrics for the experiment — this REPLACES all existing saved-metric links, it does not append. To add or remove one, first read the experiment's current saved_metrics via experiment-get and resend the full set. Pass an empty array to detach all shared metrics."
},
+ "ScannerEstimateRecordingsFilterSchema": {
+ "description": "Which recordings to count, as a `RecordingsQuery`. Omit every filter to count every recording. The date range is ignored, because the estimate counts a recent window (`window_days` in the response) and scales it to 30 days.",
+ "type": "object",
+ "properties": {
+ "kind": {
+ "default": "RecordingsQuery",
+ "type": "string",
+ "const": "RecordingsQuery"
+ },
+ "events": {
+ "description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "actions": {
+ "description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "properties": {
+ "description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "having_predicates": {
+ "description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "console_log_filters": {
+ "description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "operand": {
+ "description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.",
+ "anyOf": [
+ {
+ "type": "string",
+ "enum": ["AND", "OR"]
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "filter_test_accounts": {
+ "description": "Leave out recordings from internal and test accounts.",
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": {}
+ },
+ "ScannerRecordingsFilterSchema": {
+ "description": "Which recordings the scanner watches, as a `RecordingsQuery`. Omit every filter to watch every new recording. The date range is ignored, because the schedule controls time.",
+ "type": "object",
+ "properties": {
+ "kind": {
+ "default": "RecordingsQuery",
+ "type": "string",
+ "const": "RecordingsQuery"
+ },
+ "events": {
+ "description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "actions": {
+ "description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "properties": {
+ "description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "having_predicates": {
+ "description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "console_log_filters": {
+ "description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "operand": {
+ "description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.",
+ "anyOf": [
+ {
+ "type": "string",
+ "enum": ["AND", "OR"]
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "filter_test_accounts": {
+ "description": "Leave out recordings from internal and test accounts.",
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": {}
+ },
+ "ScannerUpdateRecordingsFilterSchema": {
+ "description": "The filter that replaces the scanner's current one, as a `RecordingsQuery`. It is not merged: any field you leave out is cleared, and `{}` watches every new recording. To change part of the filter, read the current one with `vision-scanners-get`, change it, and send it back in full. The date range is ignored, because the schedule controls time.",
+ "type": "object",
+ "properties": {
+ "kind": {
+ "default": "RecordingsQuery",
+ "type": "string",
+ "const": "RecordingsQuery"
+ },
+ "events": {
+ "description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "actions": {
+ "description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "properties": {
+ "description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "having_predicates": {
+ "description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "console_log_filters": {
+ "description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`.",
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "operand": {
+ "description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.",
+ "anyOf": [
+ {
+ "type": "string",
+ "enum": ["AND", "OR"]
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "filter_test_accounts": {
+ "description": "Leave out recordings from internal and test accounts.",
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": {}
+ },
"ScoreDefinitionConfigSchema": {
"anyOf": [
{
diff --git a/services/mcp/src/generated/replay_vision/api.ts b/services/mcp/src/generated/replay_vision/api.ts
index 664dfebaa07f..cdda1ef3b822 100644
--- a/services/mcp/src/generated/replay_vision/api.ts
+++ b/services/mcp/src/generated/replay_vision/api.ts
@@ -1073,12 +1073,6 @@ export const VisionScannersCreateBody = () => zod
.describe(
'Type-specific configuration. All scanner types require `prompt`; monitors add optional `allow_inconclusive`, classifiers add `tags`, scorers add `scale`, summarizers add optional `length`.'
),
- query: zod
- .unknown()
- .optional()
- .describe(
- 'Persisted `RecordingsQuery` shape used to pick candidate sessions. `date_from`\/`date_to` are stripped on save — the schedule controls time, not the user.'
- ),
sampling_rate: zod
.number()
.min(visionScannersCreateBodySamplingRateMin)
@@ -1258,12 +1252,6 @@ export const VisionScannersPartialUpdateBody = () => zod
.describe(
'Type-specific configuration. All scanner types require `prompt`; monitors add optional `allow_inconclusive`, classifiers add `tags`, scorers add `scale`, summarizers add optional `length`.'
),
- query: zod
- .unknown()
- .optional()
- .describe(
- 'Persisted `RecordingsQuery` shape used to pick candidate sessions. `date_from`\/`date_to` are stripped on save — the schedule controls time, not the user.'
- ),
sampling_rate: zod
.number()
.min(visionScannersPartialUpdateBodySamplingRateMin)
@@ -2433,12 +2421,6 @@ export const visionScannersEstimateCreateBodyExperimentOneVariantsItemMax = 400
export const VisionScannersEstimateCreateBody = () => zod
.object({
- query: zod
- .unknown()
- .optional()
- .describe(
- 'Proposed `RecordingsQuery` for the candidate filter. `date_from`\/`date_to` are ignored — the estimate scans a recent window (`window_days` in the response) and scales it to 30 days. Omit to estimate against all recordings.'
- ),
sampling_rate: zod
.number()
.min(visionScannersEstimateCreateBodySamplingRateMin)
diff --git a/services/mcp/src/schema/tool-inputs.ts b/services/mcp/src/schema/tool-inputs.ts
index eb664342ea7e..827b35bb4ec1 100644
--- a/services/mcp/src/schema/tool-inputs.ts
+++ b/services/mcp/src/schema/tool-inputs.ts
@@ -1497,3 +1497,48 @@ export const FlagRulesV2UpdateInputSchema = z.preprocess(
.describe('The complete new configuration. It replaces the stored `filters`.'),
})
)
+
+// A scanner's recording filter, as the replay vision tools take it. The API validates the full
+// `RecordingsQuery`; inlining that schema in every scanner tool costs agents hundreds of kilobytes each,
+// so this names the parts a scanner filters on and lets each item through for the API to check.
+const RecordingFilterItemsSchema = z.array(z.record(z.string(), z.unknown()))
+
+const ScannerRecordingsFilterFields = z
+ .object({
+ kind: z.literal('RecordingsQuery').default('RecordingsQuery'),
+ events: RecordingFilterItemsSchema.nullish().describe(
+ 'Events a recording must contain, such as `{"id": "$pageview", "type": "events", "order": 0}`. Each can carry `properties` that filter that event.'
+ ),
+ actions: RecordingFilterItemsSchema.nullish().describe(
+ 'Saved actions a recording must contain, such as `{"id": 12, "type": "actions", "order": 0}`.'
+ ),
+ properties: RecordingFilterItemsSchema.nullish().describe(
+ 'Recording, session, person and cohort filters, such as `{"type": "recording", "key": "visited_page", "value": "/checkout", "operator": "icontains"}` or `{"type": "cohort", "key": "id", "value": 7, "operator": "in"}`.'
+ ),
+ having_predicates: RecordingFilterItemsSchema.nullish().describe(
+ 'Duration filters, such as `{"type": "recording", "key": "active_seconds", "value": 60, "operator": "gt"}`. These always apply with AND, whatever `operand` says.'
+ ),
+ console_log_filters: RecordingFilterItemsSchema.nullish().describe(
+ 'Console log filters, such as `{"type": "log_entry", "key": "level", "value": ["error"], "operator": "exact"}`.'
+ ),
+ operand: z
+ .enum(['AND', 'OR'])
+ .nullish()
+ .describe(
+ 'How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.'
+ ),
+ filter_test_accounts: z.boolean().nullish().describe('Leave out recordings from internal and test accounts.'),
+ })
+ .passthrough()
+
+export const ScannerRecordingsFilterSchema = ScannerRecordingsFilterFields.optional().describe(
+ 'Which recordings the scanner watches, as a `RecordingsQuery`. Omit every filter to watch every new recording. The date range is ignored, because the schedule controls time.'
+)
+
+export const ScannerUpdateRecordingsFilterSchema = ScannerRecordingsFilterFields.optional().describe(
+ "The filter that replaces the scanner's current one, as a `RecordingsQuery`. It is not merged: any field you leave out is cleared, and `{}` watches every new recording. To change part of the filter, read the current one with `vision-scanners-get`, change it, and send it back in full. The date range is ignored, because the schedule controls time."
+)
+
+export const ScannerEstimateRecordingsFilterSchema = ScannerRecordingsFilterFields.optional().describe(
+ 'Which recordings to count, as a `RecordingsQuery`. Omit every filter to count every recording. The date range is ignored, because the estimate counts a recent window (`window_days` in the response) and scales it to 30 days.'
+)
diff --git a/services/mcp/src/tools/generated/replay_vision.ts b/services/mcp/src/tools/generated/replay_vision.ts
index 0fb66150aa17..dd22cce973a4 100644
--- a/services/mcp/src/tools/generated/replay_vision.ts
+++ b/services/mcp/src/tools/generated/replay_vision.ts
@@ -4,6 +4,11 @@ import { z } from 'zod'
import type { Schemas } from '@/api/generated'
import * as orvalSchemas from '@/generated/replay_vision/api'
import { withUiApp } from '@/resources/ui-apps'
+import {
+ ScannerEstimateRecordingsFilterSchema,
+ ScannerRecordingsFilterSchema,
+ ScannerUpdateRecordingsFilterSchema,
+} from '@/schema/tool-inputs'
import { castBooleanToString } from '@/tools/cast-helpers'
import {
withPostHogUrl,
@@ -959,7 +964,7 @@ const visionScannersCounts = (): ToolBase<
const VisionScannersCreateSchema = () => {
const VisionScannersCreateBody = orvalSchemas.VisionScannersCreateBody()
- return VisionScannersCreateBody
+ return VisionScannersCreateBody.extend({ query: ScannerRecordingsFilterSchema })
}
const visionScannersCreate = (): ToolBase<
@@ -995,9 +1000,6 @@ const visionScannersCreate = (): ToolBase<
if (params.scanner_config !== undefined) {
body['scanner_config'] = params.scanner_config
}
- if (params.query !== undefined) {
- body['query'] = params.query
- }
if (params.sampling_rate !== undefined) {
body['sampling_rate'] = params.sampling_rate
}
@@ -1025,6 +1027,9 @@ const visionScannersCreate = (): ToolBase<
if (params.experiment_targeting !== undefined) {
body['experiment_targeting'] = params.experiment_targeting
}
+ if (params.query !== undefined) {
+ body['query'] = params.query
+ }
const result = await context.api.request<Schemas.ReplayScanner>({
method: 'POST',
path: `/api/projects/${encodeURIComponent(String(projectId))}/vision/scanners/`,
@@ -1137,7 +1142,7 @@ const visionScannersDuplicate = (): ToolBase<
const VisionScannersEstimateSchema = () => {
const VisionScannersEstimateCreateBody = orvalSchemas.VisionScannersEstimateCreateBody()
- return VisionScannersEstimateCreateBody
+ return VisionScannersEstimateCreateBody.extend({ query: ScannerEstimateRecordingsFilterSchema })
}
const visionScannersEstimate = (): ToolBase<
@@ -1149,9 +1154,6 @@ const visionScannersEstimate = (): ToolBase<
handler: async (context: Context, params: z.infer<ReturnType<typeof VisionScannersEstimateSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const body: Record<string, unknown> = {}
- if (params.query !== undefined) {
- body['query'] = params.query
- }
if (params.sampling_rate !== undefined) {
body['sampling_rate'] = params.sampling_rate
}
@@ -1170,6 +1172,9 @@ const visionScannersEstimate = (): ToolBase<
if (params.experiment !== undefined) {
body['experiment'] = params.experiment
}
+ if (params.query !== undefined) {
+ body['query'] = params.query
+ }
const result = await context.api.request<Schemas.EstimateResponse>({
method: 'POST',
path: `/api/projects/${encodeURIComponent(String(projectId))}/vision/scanners/estimate/`,
@@ -1700,7 +1705,9 @@ const visionScannersSelfDrivingStats = (): ToolBase<
const VisionScannersUpdateSchema = () => {
const VisionScannersPartialUpdateBody = orvalSchemas.VisionScannersPartialUpdateBody()
const VisionScannersPartialUpdateParams = orvalSchemas.VisionScannersPartialUpdateParams()
- return VisionScannersPartialUpdateParams.omit({ project_id: true }).extend(VisionScannersPartialUpdateBody.shape)
+ return VisionScannersPartialUpdateParams.omit({ project_id: true })
+ .extend(VisionScannersPartialUpdateBody.shape)
+ .extend({ query: ScannerUpdateRecordingsFilterSchema.optional() })
}
const visionScannersUpdate = (): ToolBase<ReturnType<typeof VisionScannersUpdateSchema>, Schemas.ReplayScanner> => ({
@@ -1733,9 +1740,6 @@ const visionScannersUpdate = (): ToolBase<ReturnType<typeof VisionScannersUpdate
if (params.scanner_config !== undefined) {
body['scanner_config'] = params.scanner_config
}
- if (params.query !== undefined) {
- body['query'] = params.query
- }
if (params.sampling_rate !== undefined) {
body['sampling_rate'] = params.sampling_rate
}
@@ -1763,6 +1767,9 @@ const visionScannersUpdate = (): ToolBase<ReturnType<typeof VisionScannersUpdate
if (params.experiment_targeting !== undefined) {
body['experiment_targeting'] = params.experiment_targeting
}
+ if (params.query !== undefined) {
+ body['query'] = params.query
+ }
const result = await context.api.request<Schemas.ReplayScanner>({
method: 'PATCH',
path: `/api/projects/${encodeURIComponent(String(projectId))}/vision/scanners/${encodeURIComponent(String(params.id))}/`,
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-create.json
index c3ce5ae708ef..2490eeeb36df 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-create.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-create.json
@@ -1,6 +1,5 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
- "description": "A Replay Vision scanner: its type, targeting query, and AI configuration.",
"properties": {
"creation_method": {
"anyOf": [
@@ -108,7 +107,129 @@
"type": "string"
},
"query": {
- "description": "Persisted `RecordingsQuery` shape used to pick candidate sessions. `date_from`/`date_to` are stripped on save — the schedule controls time, not the user."
+ "additionalProperties": {},
+ "description": "Which recordings the scanner watches, as a `RecordingsQuery`. Omit every filter to watch every new recording. The date range is ignored, because the schedule controls time.",
+ "properties": {
+ "actions": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`."
+ },
+ "console_log_filters": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`."
+ },
+ "events": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event."
+ },
+ "filter_test_accounts": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Leave out recordings from internal and test accounts."
+ },
+ "having_predicates": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says."
+ },
+ "kind": {
+ "const": "RecordingsQuery",
+ "default": "RecordingsQuery",
+ "type": "string"
+ },
+ "operand": {
+ "anyOf": [
+ {
+ "enum": ["AND", "OR"],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND."
+ },
+ "properties": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`."
+ }
+ },
+ "type": "object"
},
"sampling_mode": {
"description": "Quality pre-filter applied before random sampling. focused = top sessions only, balanced = drops the lowest-quality, comprehensive = no filter (default).\n\n* `focused` - Focused\n* `balanced` - Balanced\n* `comprehensive` - Comprehensive",
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-estimate.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-estimate.json
index ba578daf7927..0c16cd539b93 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-estimate.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-estimate.json
@@ -1,6 +1,5 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
- "description": "Body of POST /vision/scanners/estimate/ — a proposed, unsaved scanner config.",
"properties": {
"experiment": {
"anyOf": [
@@ -79,7 +78,129 @@
"type": "string"
},
"query": {
- "description": "Proposed `RecordingsQuery` for the candidate filter. `date_from`/`date_to` are ignored — the estimate scans a recent window (`window_days` in the response) and scales it to 30 days. Omit to estimate against all recordings."
+ "additionalProperties": {},
+ "description": "Which recordings to count, as a `RecordingsQuery`. Omit every filter to count every recording. The date range is ignored, because the estimate counts a recent window (`window_days` in the response) and scales it to 30 days.",
+ "properties": {
+ "actions": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`."
+ },
+ "console_log_filters": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`."
+ },
+ "events": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event."
+ },
+ "filter_test_accounts": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Leave out recordings from internal and test accounts."
+ },
+ "having_predicates": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says."
+ },
+ "kind": {
+ "const": "RecordingsQuery",
+ "default": "RecordingsQuery",
+ "type": "string"
+ },
+ "operand": {
+ "anyOf": [
+ {
+ "enum": ["AND", "OR"],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND."
+ },
+ "properties": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`."
+ }
+ },
+ "type": "object"
},
"sampling_mode": {
"default": "comprehensive",
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-update.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-update.json
index a2b5ffe0ff73..05e8e7f85b23 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-update.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-update.json
@@ -111,7 +111,129 @@
"type": "string"
},
"query": {
- "description": "Persisted `RecordingsQuery` shape used to pick candidate sessions. `date_from`/`date_to` are stripped on save — the schedule controls time, not the user."
+ "additionalProperties": {},
+ "description": "The filter that replaces the scanner's current one, as a `RecordingsQuery`. It is not merged: any field you leave out is cleared, and `{}` watches every new recording. To change part of the filter, read the current one with `vision-scanners-get`, change it, and send it back in full. The date range is ignored, because the schedule controls time.",
+ "properties": {
+ "actions": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`."
+ },
+ "console_log_filters": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`."
+ },
+ "events": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event."
+ },
+ "filter_test_accounts": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Leave out recordings from internal and test accounts."
+ },
+ "having_predicates": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says."
+ },
+ "kind": {
+ "const": "RecordingsQuery",
+ "default": "RecordingsQuery",
+ "type": "string"
+ },
+ "operand": {
+ "anyOf": [
+ {
+ "enum": ["AND", "OR"],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND."
+ },
+ "properties": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`."
+ }
+ },
+ "type": "object"
},
"sampling_mode": {
"description": "Quality pre-filter applied before random sampling. focused = top sessions only, balanced = drops the lowest-quality, comprehensive = no filter (default).\n\n* `focused` - Focused\n* `balanced` - Balanced\n* `comprehensive` - Comprehensive",