list_active_projects to find your project, then list_conversions and list_attribution_models to resolve the right IDs, and finally run_report to fetch the data.
session_id parameter returned by analyze_request. The assistant handles this automatically — you do not need to manage session IDs yourself.AI agent orchestration
Internal tools that help AI agents plan and validate their work. These are called automatically by the assistant — you do not need to use them directly.analyze_request
analyze_request
clarify, the assistant resolves the ambiguity and calls again. If status is proceed, the assistant follows the returned approach.Parameters:analyze_response
analyze_response
approved, the assistant presents the response incorporating any suggestions. If status is revise, the assistant makes corrections and calls again with an updated draft.Parameters:approved or revise) and suggestions.get_report_template
get_report_template
html if you can write files to disk, jsx if you render artifacts inline.Parameters:- “Build me a visual report for last month’s performance”
- “Create a branded dashboard with the report template”
Projects and account
Tools for creating, managing, and inspecting projects and user accounts.list_active_projects
list_active_projects
bigqueryProjectId, bigqueryDatasetId). Super users also see serviceAccountEmail.Parameters: NoneReturns: Array of project objects with ID, name, timezone, type, account info, and BigQuery settings.Example prompts:- “List all my SegmentStream projects”
- “Which projects do I have access to?”
- “What is the BigQuery dataset ID for my project?”
get_project
get_project
attributionAdjustment, maxAttributionWindow, workflowState, and billingAccount.Parameters:- “Show me the details of project X”
- “What timezone and currency is this project configured with?”
- “What features are enabled for this project?”
create_project
create_project
projectId and serviceAccountEmail.Parameters:projectId and serviceAccountEmail.Example prompts:- “Create a new project for example.com in the US Eastern timezone with USD currency”
- “Set up a new SegmentStream project for my website”
update_project
update_project
- “Change the project timezone to Europe/Berlin”
- “Update the project currency to EUR”
- “Rename the project to newsite.com”
get_current_user
get_current_user
- “Who am I logged in as?”
- “What role do I have?”
get_project_members
get_project_members
- “Who has access to this project?”
- “List all project members and their roles”
invite_teammate
invite_teammate
- “Invite [email protected] to help connect BigQuery”
- “Add my colleague as a viewer on this project”
Data sources
Tools for connecting, inspecting, and managing advertising platforms and their import status.list_data_sources
list_data_sources
- “What ad platforms are connected to this project?”
- “Show me all data sources”
- “Which data sources are enabled?”
get_data_source
get_data_source
isEnabled, isAuthenticated, options, authMeta, and workflow status.Parameters:- “Show me the configuration of the Facebook data source”
- “Is the Google Ads data source authenticated?”
get_data_source_logs
get_data_source_logs
startedAt, fillDate, status, errors, and message.Parameters:- “Show me the recent import logs for our Facebook data source”
- “Are there any import errors for Google Ads?”
- “When was the last successful import for this data source?”
list_available_data_sources
list_available_data_sources
oauth2 or api_key), and category (analytics, advertising, crm).Parameters: NoneReturns: Array of supported data source types with display name, auth method, and category.Example prompts:- “What ad platforms does SegmentStream support?”
- “Which data sources use OAuth for authentication?”
- “Show me all available CRM data sources”
connect_data_source
connect_data_source
- “Connect Google Ads to this project”
- “Add Meta Ads as a data source”
- “Set up a Google Analytics 4 connection”
disconnect_data_source
disconnect_data_source
connect_data_source. Use when: wrong account selected, insufficient OAuth scopes, or broken connection state.Parameters:- “Disconnect the Google Ads data source so I can reconnect with a different account”
- “Reset the Facebook data source connection”
connect_bigquery
connect_bigquery
configure (select GCP project, location, or dataset), grant_access (service account needs permissions), or connected (done). Pass selections back via parameters.Parameters:configure, grant_access, or connected).Example prompts:- “Connect BigQuery to my project”
- “Set up BigQuery with my GCP project my-project-123 in the EU region”
Conversions
Tools for creating, updating, and inspecting conversion definitions, statistics, and geographic breakdowns.list_conversions
list_conversions
online_purchase, online_event, sql, combined, probabilistic), counting behavior, and key configuration.Parameters:- “What conversions are configured in this project?”
- “List all active conversions”
- “Show me the conversion IDs I need for reporting”
get_conversion
get_conversion
online_purchase/online_event/sql), counting behavior, matching conditions, custom SQL, audiences, and combined conversions.Parameters:- “Show me how the Purchase conversion is configured”
- “What matching conditions does this conversion use?”
- “Show me the SQL for this custom conversion”
create_conversion
create_conversion
online_purchase for tracked website purchases, online_event for tracked website events like sign-ups or form fills (requires matching_conditions), sql for conversions from custom SQL joining external data like CRM (requires custom_sql). Before setting matching conditions, use list_filter_options and query_filter_option_values (with tool: "create_conversion") to discover available fields and values.Parameters:- “Create a Purchase conversion”
- “Add a Sign Up conversion that tracks the sign_up event”
- “Create a SQL conversion for CRM leads”
update_conversion
update_conversion
- “Rename the Purchase conversion to Online Purchase”
- “Change the counting to once per user with a 30-day window”
- “Update the SQL for this CRM conversion”
list_conversion_fields
list_conversion_fields
query_conversion_records to discover what data is available.Parameters:- “What fields are available for the Lead conversion?”
- “Show me the CRM fields I can query for this conversion”
- “List conversion record fields”
get_conversion_statistics
get_conversion_statistics
totalConversions, totalSessions, totalValues, visitors, conversionsHistory (per date), and exportsHistory.Parameters:- “How many purchases happened last month?”
- “Show me the daily conversion trend for the past 30 days”
- “What is the total conversion value this quarter?”
get_conversions_by_country
get_conversions_by_country
- “Which countries had the most purchases last month?”
- “Break down lead conversions by country for Q4”
query_conversion_records
query_conversion_records
list_conversion_fields first to discover available fields. When attribution_id is provided, filters support report dimensions (channel, campaign_name). For aggregated performance analytics (ROAS, CPA, conversion counts by dimension), use run_report instead.Parameters:- “Show me the last 50 leads with their email and source”
- “List all conversions from Generic Search last month with CRM fields”
- “Which customers converted from Meta Ads this week?”
Attribution models
Tools for inspecting and managing attribution model configurations.list_attribution_models
list_attribution_models
attributionWindow, adjustment, filter, dimension, and isDisabled.Parameters:- “What attribution models are available?”
- “Which attribution model is the default?”
- “Show me all attribution model IDs”
get_attribution_model
get_attribution_model
- “Show me the configuration of the Multi-Touch attribution model”
- “What is the attribution window for the Last Click model?”
- “Does this model use self-reported attribution?”
create_attribution_model
create_attribution_model
significant_touch_rule (last-click only) defines which touches the engine treats as “significant” credit recipients in the cascade: (1) credit goes to the most recent touch matching the rule, (2) if no touch matches, credit falls back to the most recent non-direct touch, (3) if the journey has no non-direct touches, credit falls back to direct.Parameters:get_attribution_model.Example prompts:- “Create a last-click attribution model with a 30-day window”
- “Add a first-click model called Acquisition”
- “Create a last paid non-brand attribution model”
update_attribution_model
update_attribution_model
get_attribution_model.Example prompts:- “Change the attribution window of the Last Click model to 60 days”
- “Update the significant-touch rule to exclude direct traffic”
- “Disable self-reported reattribution on this model”
Reports and analytics
Tools for querying campaign performance data — the primary way to pull metrics from SegmentStream.run_report
run_report
query_conversion_records. Use query_filter_option_values to discover exact filter values. Use format: "csv" for fewer tokens.All query options live under a single settings object — same shape get_saved_report returns and save_report accepts. To execute a saved report, pass saved_report_id and use settings as a partial override (omit a field to keep saved, arrays replace entirely, explicit null clears).Parameters:comparison_totals when comparison_date_range is set).Example prompts:- “Show me the top 10 campaigns by cost for the last 30 days”
- “What is the ROAS by ad platform for last month?”
- “Give me a breakdown of conversions by source/medium and country”
- “Compare campaign performance between this month and last month”
- “Run my Performance Overview saved report with last_60_days instead”
run_report_timeseries
run_report_timeseries
saved_report_id; the saved chart config (chart.date_granularity, chart.metrics) becomes the base and settings is a partial override.Parameters:- “Show me the daily cost trend for the past 30 days”
- “Plot weekly conversions over the last 3 months”
- “Chart the ROAS trend by week for Facebook campaigns”
list_saved_reports
list_saved_reports
run_report (or run_report_timeseries) with saved_report_id.Parameters:id, name, project_id, url (admin panel link), and settings.Example prompts:- “What reports are saved in this project?”
- “Find the saved report for channel performance”
- “Show me all saved reports and pick the one that matches our weekly review”
get_saved_report
get_saved_report
save_report (to duplicate or update) or to run_report / run_report_timeseries (to execute with overrides). Typical flow: get → mutate → save or get → mutate → run.Parameters:id, name, project_id, url, settings).Example prompts:- “Show me the configuration of the Performance Overview report”
- “What dimensions and metrics does this saved report use?”
save_report
save_report
id to CREATE (server generates a UUID), pass an existing id to UPDATE. To DUPLICATE, call get_saved_report, mutate the returned settings, and call save_report WITHOUT the id. Returns the saved report including a direct URL to the admin panel. The settings shape is identical to what get_saved_report returns and run_report accepts. If chart.metrics is set but chart.rows is omitted, a default Total row is auto-populated so the chart renders.Parameters:id, name, project_id, url, settings.Example prompts:- “Save this report as ‘Weekly channel review’”
- “Duplicate the Performance Overview report and add a country dimension”
- “Update the saved report to use last_30_days”
Filters
Tools for discovering valid filter fields and their values. Used before building filter expressions forrun_report, query_conversion_records, conversion matching conditions, grouped dimension rules, and attribution model significant-touch rules.
list_filter_options
list_filter_options
- For
create_conversion/update_conversion: returns GA4 field names (event_name,items.item_category,event_params.*,geo.country, etc.). - For
create_grouped_dimension/update_grouped_dimension: returns base dimensions only (campaign_name,ad_platform,country, etc. — no grouped dimensions). - For
run_report/create_attribution_model/update_attribution_model: returns base dimensions and grouped dimensions (Channel, etc.).
- “What fields can I filter on in run_report?”
- “List GA4 fields I can use in a conversion matching condition”
- “Show me the base dimensions available when defining a Channel rule”
query_filter_option_values
query_filter_option_values
list_filter_options to discover what values exist for a specific option.- For conversion tools: accepts GA4 field names (
event_name,items.item_category,event_params.subscription,geo.country). - For dimensions (
run_report,create_grouped_dimension): queries session-level data and grouped dimension groups (e.g.channel).
- “What campaign names are available in this project?”
- “List all ad platform values”
- “Show me the values of the Channel dimension”
- “What values exist for the event_params.subscription field?”
User journey
Tools for tracing individual user paths and attribution credit distribution.get_user_journey
get_user_journey
anonymous_id or user_id. Useful for debugging attribution and understanding individual user paths.Parameters:- “Show me the user journey for anonymous ID
abc123over the last 30 days” - “What touchpoints led to the last conversion for user
[email protected]?” - “Trace the journey for this anonymous ID and show attribution credits”
debug_user_journey
debug_user_journey
- “Show me the SQL behind this user journey query”
- “Debug the user journey query for this anonymous ID”
BigQuery
Direct SQL access to your project’s BigQuery dataset. Only available for projects with their own Google BigQuery (bring-your-own). Not available for SegmentStream-managed projects — userun_report, query_conversion_records, and query_filter_option_values instead.
bigquery_execute_sql
bigquery_execute_sql
hitsSet instead of project.dataset.hitsSet). Best for: raw event data exploration, PII/CRM field lookups, schema inspection, and custom analysis the report API cannot express. For questions involving channel attribution, campaign performance, or conversion metrics, prefer run_report — it uses the attribution engine automatically.Parameters:- “Run a query to count sessions by country for last week”
- “Show me the schema of the sessions table”
- “Query the raw events table for the last 24 hours”
- “How many unique users visited the site yesterday?”
bigquery_get_table_schema
bigquery_get_table_schema
null if the table does not exist. Use list_active_projects to find the project ID.Parameters:- “What columns does the sessions table have?”
- “Show me the schema for hitsSet”
- “What fields are available in the conversions table?”
Grouped dimensions
Tools for inspecting and managing grouped dimensions — categorizations that bucket base dimension values into named groups (e.g., the Channel dimension groups campaigns into “Paid Search”, “Paid Social”, “Organic Search”).list_grouped_dimensions
list_grouped_dimensions
run_report dimensions or get_grouped_dimension. channel is a built-in alias for the Channel dimension.Parameters:- “What grouped dimensions are available?”
- “List all dimension keys I can use in reports”
get_grouped_dimension
get_grouped_dimension
channel for the Channel dimension. Returns groups in evaluation order — each has a name and a filter using base dimensions like ad_platform, campaign_name, utm_source. Use this before update_grouped_dimension to see current groups.Parameters:- “Show me the Channel dimension groups”
- “How is this grouped dimension configured?”
create_grouped_dimension
create_grouped_dimension
ad_platform, campaign_name, campaign_type, utm_source, utm_medium, source_medium, country, device, etc.). Use query_filter_option_values (with tool: "create_grouped_dimension") to discover exact values before building group filter rules. If no groups are provided, all traffic goes to “Other”.Parameters:status: "created", key, name, and the list of group names.Example prompts:- “Create a Region grouped dimension with EMEA and North America groups”
- “Add a Brand vs Non-Brand dimension”
update_grouped_dimension
update_grouped_dimension
channel), update groups that define how traffic is categorized. Each group has a name and a filter. Filters use base dimensions only. Groups are evaluated in order — first match wins. Put specific rules first, broad rules last. Traffic not matching any group goes to Other automatically.Filter shape — single rule: { "option": "ad_platform", "operator": "equals", "value": "Facebook" }. Compound: { "or": [{ "option": "utm_source", "operator": "contains", "value": "chatgpt" }, { "option": "utm_source", "operator": "contains", "value": "perplexity" }] }.Parameters:status: "updated", key, name, list of channel names, and catch_all: "Other".Example prompts:- “Add a TikTok Ads channel to the Channel dimension”
- “Update the Channel dimension to include an Organic AI group”
- “Rename the Brand Search group”
Audiences
Tools for inspecting audience definitions and memberships.list_audiences
list_audiences
isForever, filter, membershipDurationDays, and status for each audience.Parameters:- “What audiences are defined in this project?”
- “List all audiences associated with the Purchase conversion”
get_audience
get_audience
projectId, isForever, filter, filterSql, membershipDurationDays, status, createdAt, and updatedAt.Parameters:- “Show me the filter criteria for this audience”
- “How long do users stay in this audience?”
query_audiences_by_client_id
query_audiences_by_client_id
audienceId, audienceName, entryTime, and expirationTime for each membership.Parameters:- “What audiences does anonymous ID
abc123belong to?” - “Show me audience memberships for this user over the last 30 days”
get_audiences_inclusion
get_audiences_inclusion
allUsers count. Optionally filter by ML model.Parameters:- “What percentage of users are in each audience?”
- “Show me audience inclusion statistics”
Workflows
Tools for monitoring data processing workflows.list_workflows
list_workflows
- “Show me the recent workflows”
- “What data processing jobs ran today?”
get_workflow_status
get_workflow_status
- “What is the status of this workflow?”
- “Did this workflow complete successfully?”
- “Show me any errors from the last workflow run”
Cost data quality
Tools for monitoring advertising cost data accuracy.get_cost_data_quality
get_cost_data_quality
- “What is the cost data quality score for this project?”
- “Show me the data quality for the Facebook data source”
- “How has cost data quality changed over the last 30 days?”
Identity graph
Tools for inspecting user identity stitching.get_identity_graph_statistics
get_identity_graph_statistics
- “Show me the identity graph statistics”
- “How many users have cross-device stitching?”
- “What is the user stitching distribution for the last 30 days?”
Incidents
Tools for checking project health alerts.list_incidents
list_incidents
- “Are there any active incidents?”
- “Show me recent errors for this project”
- “List all incidents from the last week”
Classifiers (ML models)
Tools for inspecting ML-based classifiers used for conversion scoring.list_classifiers
list_classifiers
- “What ML classifiers are configured?”
- “Show me the classifier settings for this project”
get_classifier
get_classifier
- “Show me the details of this classifier”
- “What model does this classifier use?”
list_classifier_models
list_classifier_models
- “What classifier models are available?”
- “Show me the pricing for classifier models”
Portfolios (budget optimization)
Tools for inspecting portfolio configurations, performance history, and optimization scenarios.list_portfolios
list_portfolios
potentialMetric, actualMetric, actualSpend), targetsCount, isReady, and lastApplyTime.Parameters:- “What portfolios are configured in this project?”
- “List all optimization portfolios”
- “Which portfolios are ready for optimization?”
get_portfolio_history
get_portfolio_history
portfolio_id (and optional period), returns a summary with per-period rows and plots. When start_date and end_date are provided, returns detailed period data including per-campaign breakdowns.Parameters:- “Show me the portfolio performance over the last 3 months”
- “What was the campaign-level breakdown for January?”
- “How has this portfolio performed over the last 6 months?”
get_portfolio_optimization
get_portfolio_optimization
- “Show me the optimization recommendations for this portfolio”
- “What would the optimal budget allocation look like with a $50,000 monthly budget?”
- “Show me the diminishing returns curves for portfolio targets”
Experiments (geo tests)
Tools for inspecting geo-lift experiments.list_experiments
list_experiments
- “What experiments are running?”
- “Show me all geo tests and their status”
- “List completed experiments with their results”
get_experiment
get_experiment
- “Show me the results of this geo test”
- “What was the measured lift in this experiment?”
- “Show me the experiment preparation details”
list_experiment_custom_parameter_keys
list_experiment_custom_parameter_keys
- “What custom parameters can I use for geo test segmentation?”
- “List available custom parameter keys for experiments”