IQRush

Get a one-pager executive summary for a completed measurement run (precomputed). Bundles headline metrics, top cited domains, the brand's own-domain block, and citation/mention breakdown into a single call — use this instead of chaining get_job_summary + get_placement_targets separately when you need the full picture for a report or summary narrative. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs (UUID or numeric legacy id).

get_executive_summary

Bootstrap dimension-effect decomposition for one citation domain. Returns per-level effects for platform, topic, intent, and prompt_type (effect = cell share minus grand mean), dominant_pattern, and R2 decomposition. Args: project_id: Project UUID from list_projects. run_id: Run ID from list_runs. domain: Domain name to analyse (required, e.g. 'example.com'). score_family: 'citation' only in this build. metric: 'share' only in this build. n_boot: Bootstrap resamples (default 200). filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}].

get_factor_analysis

Return available dimensions and metrics for the project's linked GA4 property. Returns the schema of what is available in the snapshot store: dimension names, metric names, and descriptions. Returns linked=false if no GA4 property is linked. Args: project_id: Project UUID from list_projects.

get_ga4_metadata

Return current active users for the project's linked GA4 property. Note: This implementation surfaces ingested snapshot data only. Realtime GA4 API data is not available — use get_ga4_report for historical channel performance. Args: project_id: Project UUID from list_projects.

get_ga4_realtime

Run a GA4 data report for the project's linked property. Returns the latest snapshot and history of sessions, users, pageviews, bounce rate, conversions, revenue, and channel breakdown. Returns linked=false if no GA4 property is linked. Data is ingested periodically — not live. Args: project_id: Project UUID from list_projects. limit: Number of historical snapshots to return (default 6, max 24).

get_ga4_report

Get brand groundedness (citation-backed mention rate) with CIs (live). Fraction of brand mentions that are backed by a citation in the same response. Wilson CI. Default subject is self_and_competitors. New-pipeline runs return full data when the run's entity_mentions gold carries the per-mention grounded flag. Older new-pipeline runs produced before that flag existed return not_available with a rerun hint. Legacy runs always return full data. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. aggregation_level: 'entity' or 'bundle' (default). group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}]. subject: JSON entity subject spec.

get_groundedness

Get sources (domains/URLs) that ground brand mentions with CIs (live). Returns per-source share of grounding citations. denominator='grounding_pool' shows share within citations that also ground a brand mention; 'per_source' shows each domain's grounding share independently. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. denominator: 'grounding_pool' (default) or 'per_source'. aggregation_level: 'domain' (default) or 'url'. group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}]. brand_subset: 'self', 'competitors', or null (all brands). sentiment_filter: 'positive', 'negative', or null (all sentiments).

get_grounding_sources

Get headline metrics for a completed measurement run (precomputed). Faster than the equivalent live tools. Returns citation_share (Wilson+DEFF 95% CI), citation_coverage (Wilson 95% CI), mention_count, and positive_mention_count. Use get_citation_score / get_mention_score for per-domain or dimensionally-sliced results. NOTE: This tool does NOT contain results_stability. For results stability use get_results_stability instead. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs (UUID or numeric legacy id).

get_job_summary

Get mention score for brands with confidence intervals (live computation). Returns per-entity or per-bundle mention metrics. Supports entity-level resolution (individual terms) or bundle-level (grouped by brand). Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. metric: 'coverage' (Wilson, default) or 'count' (raw mention count, no CI). aggregation_level: 'entity' (default) or 'bundle'. group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}]. subject: JSON entity subject spec.

get_mention_score

Track one measurement metric across many runs — per-series timeline with 95% CI. Builds a time series across all completed runs for the project. Each series is a domain (citation), brand bundle (mention/sentiment), or other key depending on metric_family. Args: project_id: Project UUID from list_projects. metric_family: One of 'citation', 'mention', 'sentiment'. metric: Specific metric — 'share'/'coverage' (citation), 'coverage' (mention), 'net'/'positive'/'negative' (sentiment). aggregation_level: 'domain' (citation), 'bundle' (mention/sentiment). entities: Filter to specific brand entities. domains: Filter to specific domains. top_n: Number of top series to return by latest value (default 6). run_ids: Restrict to specific run UUIDs.

get_metric_timeseries

Bootstrap contrast for one domain/entity across two conditions or two runs. Within-run: pass condition_a and condition_b as JSON dicts with dimension keys. Cross-run: pass run_id_a and run_id_b (any two runs, adjacent or not). In cross-run mode, set run_id = run_id_b (the newer / checkpoint run) — it is used as the URL path parameter even though the contrast covers both runs. If contrast.value / ci.lower / ci.upper are all null in the response, the domain or entity had no data in one or both runs — this is NOT a "no difference" result, it means insufficient data for the test. Args: project_id: Project UUID from list_projects. run_id: Within-run mode: the run to contrast within. Cross-run mode: set to run_id_b (the newer run). entity_or_domain: Domain or entity string to contrast (required). score_family: 'citation' only in this build. metric: 'share' or 'count'. condition_a: Condition for A side e.g. {"platform":"Gemini"} or '{"platform":"Gemini"}'. condition_b: Condition for B side e.g. {"platform":"Perplexity Search"}. run_id_a: First run ID (cross-run mode). run_id_b: Second run ID (cross-run mode). n_boot: Bootstrap resamples (default 200). filters: Array of filter objects.

get_paired_contrast

Get the top URLs by citation_share for a measurement run (precomputed). Returns up to 20 URLs ranked by citation_share, each with 95% CIs for citation_share (Wilson+DEFF) and citation_coverage (Wilson). Also returns an aggregate target_domain block for the brand's own domain(s). Use get_citation_score(aggregation_level='url') for full URL-level data with dimensional slicing. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs (UUID or numeric legacy id).

get_placement_targets

Return product-level revenue and conversion data for AI-referred sessions. Shows items viewed, added to cart, purchased, revenue, and implied conversion rates per product. Useful for identifying which products AI traffic buys most. Use when the user asks about top products, product revenue from AI, or which items AI visitors add to cart. Args: project_id: IQRush project UUID from list_projects. start_date: Start of date range (30daysAgo, 7daysAgo, or YYYY-MM-DD). end_date: End of date range (today or YYYY-MM-DD). session_source: Filter to a specific AI source (e.g. "perplexity.ai"). limit: Maximum number of products to return (default 50).

get_product_performance

Get project metadata and brand context for a single project. Returns project name, status, timestamps, and brand_context (entity bundle, competitor bundles, owned domains). Args: project_id: Project UUID from list_projects.

get_project

Per-domain rank position change with bootstrap CI and p_rank_changed. Catches dense-middle movement that share-difference tests miss. Useful when a domain has clearly moved up or down in the citation leaderboard but its absolute share change is small. BACKEND LIMITATION — previous_run only: Same constraint as screen_drift and attribute_drift. Only previous_run works. For non-adjacent run rank comparison on a specific domain, use get_paired_contrast with run_id_a/run_id_b. Args: project_id: Project UUID from list_projects. run_id: Checkpoint run ID. reference: Must be '{"type":"previous_run"}' or omitted. Any other value returns a structured error instead of running. aggregation_level: 'domain' or 'url'. n_boot: Bootstrap resamples (default 200). group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}]. subject: JSON citation subject spec.

get_rank_displacement

Compute results stability (intra-run convergence), optionally filtered by topic or platform. Use for: results stability, ranking reliability, whether data from a single run is converged. NOT for run-over-run drift — use screen_drift for that. NOT get_run or get_job_summary — both lack stability data. Convergence requires TWO independent gates — both must be true: rank_corr_ok — rank ordering has plateaued (BIC-iso plateau test) sufficiency_ok — established domains are spread far enough apart to be distinguishable is_converged = rank_corr_ok AND sufficiency_ok. results_stability.value = structural_snr_ewma (std of established shares / CI halfwidth, EWMA-smoothed). Target is 1.0 — not a correlation; do NOT compare to ~0.95. results_stability_detail includes: rank_corr_ok, sufficiency_ok, is_converged, structural_snr, snr_was_limiting, n_established, n_core, xmin, boundary_domain, boundary_domain_share. Segment counts: n_established = established domains (CI excludes zero). n_core = domains above Clauset xmin (power-law body). boundary_domain_share = minimum citation share to be in the core tier. Narrate core as: "X domains are in the core tier (above the power-law body at {boundary_domain_share:.1%} share)." Narration: is_converged=true -> "Results are stable — ranking has plateaued and domains are clearly separable (SNR={value:.2f}, target 1.0)." snr_was_limiting=true -> "Rank order is stable but domains are not yet distinguishable — collect more data." rank_corr_ok=false -> "Ranking has not yet plateaued — collect more data." Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs (UUID or numeric legacy id). filters: Optional filter objects e.g. [{"dimension":"topic","values":["vivobarefoot"]}] or [{"dimension":"platform","values":["Google"]}]. Pass null for all-up stability. aggregation_level: 'domain' (default) or 'url'.

get_results_stability

Get full detail for a single measurement run — status, data_readiness, and counts. NOTE: results_stability is always null in this response. For results stability, call get_results_stability. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs (UUID or numeric legacy id).

get_run

Return Google Search Console query performance data for a project. Shows top organic search queries with clicks, impressions, CTR, and average position. Data is sourced from the IQRush database (nightly batch sync). Empty rows do not necessarily mean GSC was never connected — check gsc_sync_status/gsc_sync_error in the response first: "error" means the nightly sync is currently failing (e.g. revoked token, insufficient GSC permission on the linked site) and rows are stale/empty because of that, not because the integration is unconfigured. Use when the user asks about organic search traffic, keyword rankings, GSC data, search impressions, CTR, or which queries drive Google clicks. Call list_projects first to resolve a project name to its project_id UUID. Args: project_id: IQRush project UUID from list_projects. start_date: Start of date range (30daysAgo, 7daysAgo, or YYYY-MM-DD). end_date: End of date range (today or YYYY-MM-DD). device: Filter by device (desktop, mobile, tablet). Omit for all devices. limit: Maximum number of query rows to return (default 100, max 5000).

get_search_console_data

Get brand sentiment rates with confidence intervals (live computation). Returns positive, negative, neutral rates (Wilson CI) or net sentiment (normal_approx CI) per entity. Default subject is self_and_competitors. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. metric: 'positive', 'negative', 'neutral', or 'net' (default: 'positive'). aggregation_level: 'entity' or 'bundle'. group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}]. subject: JSON entity subject spec.

get_sentiment

Scan for significant citation-share changes and rank displacements. Composes attribute_drift + get_rank_displacement and returns merged findings sorted by |effect|. Up to 50 findings returned with BH correction applied. BACKEND LIMITATION — previous_run only: Same constraint as screen_drift / attribute_drift / get_rank_displacement. Only compares to the immediately preceding run. For non-adjacent run comparison use get_paired_contrast with run_id_a/run_id_b per domain. Args: project_id: Project UUID from list_projects. run_id: Checkpoint run ID from list_runs. reference: Must be '{"type":"previous_run"}' or omitted. Any other value returns a structured error instead of running. kinds: Subset of ["share_change","rank_displacement"] (default: both). min_effect_size: Minimum |diff| to include (default 0). n_boot: Bootstrap resamples (default 200). group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}].

get_significant_findings

Retrieve pipeline-computed technical and SEO feature scores for a specific URL in a run. Call when the user asks about technical health of a page — page speed, Core Web Vitals, structured data, indexability, or crawl-level signals. Useful for comparing a URL's normalized scores against competitor URLs cited in the same run. For legacy runs: returns per-feature scores from gso_pipeline.feature_scores (detailed). For new-pipeline runs: returns run-level wpp aggregate metrics (url_segments when available). Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs (numeric string or UUID). url: URL or domain to inspect. Domain or full URL both accepted. feature_group: Optional group filter (e.g. 'page_speed', 'meta', 'headings'). feature_domain: Optional domain filter: 'GEN', 'SEO', 'SEO_Competitive', 'GEO' (legacy only).

get_technical_features

Summarize the trend of one metric across a run window: first vs latest value, delta, direction. Returns one trend object per tracked series. Each trend includes direction (up/down/flat), delta, pct_change, best/worst run, volatility, and whether the CI overlap indicates a likely real change. Args: project_id: Project UUID from list_projects. metric_family: One of 'citation', 'mention', 'sentiment'. metric: Specific metric within the family. aggregation_level: 'domain' (citation), 'bundle' (mention/sentiment). entities: Filter to specific brand entities. domains: Filter to specific domains. top_n: Number of top series to return by latest value (default 6). run_ids: Restrict to specific run UUIDs.

get_trend_summary

Composite brand visibility alignment diagnostic (live computation). Fans out to mention_score (coverage) and groundedness in parallel and composes three scored metrics: grounded_visibility (mention AND citation-backed, delta-method CI), named_but_unsourced (mentioned without citation backing), and owned_citation_coverage. Diagnosis label per entity: strong_alignment (M ≥ 0.5, G ≥ 0.5), named_but_unsourced (M ≥ 0.5, G < 0.3), cited_but_unnamed (M < 0.3, G ≥ 0.5), low_visibility (M < 0.3, G < 0.3), partial_alignment (all other combos). New-pipeline runs return not_available for groundedness — see get_groundedness note. Call first when the user asks about brand visibility health or the 'cited but not named' gap. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. aggregation_level: 'bundle' (default) or 'entity'. group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}]. subject: Entity subject spec e.g. '{"kind":"self_and_competitors"}'.

get_visibility_alignment

List saved baselines for a project. Baselines are named snapshots of a run used as references for drift comparisons. Returns an empty list — the baseline store is not yet provisioned in this build. Contact IQRush support to provision baselines. Args: project_id: Project UUID from list_projects.

list_baselines

List valid filter values for all slicing dimensions under a project. Returns platform, topic, prompt_type, intent, and user_profile option lists derived from the project's latest run. Pass these values to the group_by and filters parameters on measurement tools. Args: project_id: Project UUID from list_projects.

list_dimension_options

List GA4 properties linked to this project. Returns the GA4 property and GSC site URL linked to the project, or linked=false if no Google Analytics connection has been set up. Args: project_id: Project UUID from list_projects.

list_ga4_properties

Get individual statements where the specified brands are mentioned (live). Row-level drill-down: returns one row per statement-level sentence where the requested brands are mentioned. Each row includes the statement text, which citation domains/URLs ground it, and which of the requested brand terms appear. Paginated — pass the returned cursor to fetch the next page. Use prompt_type / intent / topic to narrow to a specific query bucket. Use query_id (from list_queries) to drill into a single specific query's responses. For CO-MENTION questions (which brands appear TOGETHER, and how often), use get_comention_network — this tool returns individual statement rows, not co-occurrence counts, and does NOT support an "all entities together" filter. Passing multiple entities here returns statements mentioning ANY of them, not only the ones where they co-occur. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. entities: Brand terms to filter by. Null returns all self + competitor mentions. NOTE: multiple entities = statements mentioning ANY of them (union), not a co-mention filter. For co-mention use get_comention_network. include_ungrounded: Include statements not backed by a citation (default true). include_full_response: Include the full LLM response text (default false). max_text_chars: Max characters for statement/response text (50–2000, default 500). limit: Rows per page (1–100, default 25). cursor: Opaque cursor string from a previous call for the next page. filters: Additional filter objects. prompt_type: Filter to a specific Category facet. intent: Filter to a specific Customer Intent. topic: Filter to a topic name substring. query_id: Filter to a single query ID from list_queries.

list_mention_statements

List all GSO projects in the authenticated workspace. Returns project IDs, names, and status. Use the returned project_id values with list_runs to retrieve measurement runs.

list_projects

List the queries that ran in a job with their prompt type and intent. Qualitative lookup — no scores. Returns the actual question text for each query that ran, labelled with its prompt_type and intent. When entity is provided, each row also includes a `mentioned` boolean showing whether that brand appeared in any response to that query. Args: project_id: Project UUID from list_projects. run_id: Run ID string from list_runs. prompt_type: Optional filter by Category facet. intent: Optional filter by Customer Intent. topic: Optional filter by topic name substring. entity: Optional brand term to check mention presence per query. limit: Max rows to return (1–200, default 50). IMPORTANT (totals): `n_available` is the TRUE total number of queries in the run; it is the correct answer to "how many queries ran?" — report it plainly (e.g. "140 queries ran"). Do NOT say "showing 1 of 140" for a count question; `n_returned`/`rows` only reflects how many rows you happened to request and is meaningless as a total. Only when you are actually LISTING the query rows should you note "showing N of {n_available}" (and only if truncated). Never present the returned-row count as the run's total.

list_queries

List all measurement runs for a project, newest first. Each run includes data_ready (True when project_summary insight is READY) and the run_id needed by get_run and all measurement tools. Args: project_id: Project UUID from list_projects.

list_runs

Rank tracked series by biggest movement over the run window — top risers and fallers. Returns two lists: risers (positive delta, sorted descending) and fallers (negative delta, sorted ascending), each capped at max_movers entries. Args: project_id: Project UUID from list_projects. metric_family: One of 'citation', 'mention', 'sentiment'. metric: Specific metric within the family. aggregation_level: 'domain' (citation), 'bundle' (mention/sentiment). entities: Filter to specific brand entities. domains: Filter to specific domains. top_n: Number of top series to consider (default 10). run_ids: Restrict to specific run UUIDs. max_movers: Max risers/fallers to return (default 5).

list_timeseries_movers

Fast bootstrap drift screen: did the citation landscape change between two runs? NOTE: This measures run-over-run drift (did results CHANGE between two separate runs?). It is NOT results stability. For results stability — meaning how consistent/reliable the ranking is within a single run — use get_results_stability instead. Computes rank-correlation of citation shares between checkpoint run and a reference run. is_drift_detected=true when upper CI bound < threshold. BACKEND LIMITATION — previous_run only: The only supported reference is '{"type":"previous_run"}' (the default). Passing any other reference returns a structured error — do NOT retry with a different reference shape. For a comparison between two non-adjacent runs use get_paired_contrast with run_id_a and run_id_b (covers one domain/entity at a time). Args: project_id: Project UUID from list_projects. run_id: Checkpoint (newer) run ID. reference: Must be '{"type":"previous_run"}' or omitted. Any other value returns a structured error instead of running. aggregation_level: 'domain' or 'url'. threshold: Rank-correlation threshold for drift detection (default 0.95). n_boot: Bootstrap resamples (default 200). group_by: Dimension names to group by e.g. ["platform"]. filters: Filter objects e.g. [{"dimension":"platform","values":["Google"]}].

screen_drift

Returns the user's project list and resolves the latest run in one call. Useful at the start of a new conversation, or whenever you need a project's most recent run without a separate list_projects → list_runs round-trip. TWO-PHASE FLOW: PHASE 1 — first call, no project_id: Call start_session() with no project_id. Shows the user's project list. Ask: 'Which project would you like to explore?' PHASE 2 — after user picks a project: Call start_session(project_id=<uuid>). This resolves the most recent run and returns a summary.

start_session

Return valid query-per-topic budgets that satisfy marginal balance. A balanced query set requires n_queries_per_topic to be a multiple of the LCM of all facet option counts. All returned candidates are valid values for n_queries_per_topic when designing a balanced query set across these facets. Args: facets: List of {facet_name, options} dicts describing each design dimension, e.g. [{"facet_name":"platform","options":["Google","Perplexity"]}, {"facet_name":"intent","options":["informational","commercial"]}]. n_min: Minimum queries per topic to include (default 1). n_max: Maximum queries per topic to include (default 500).

valid_query_budgets