Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.segmentstream.com/llms.txt

Use this file to discover all available pages before exploring further.

SegmentStream MCP provides 60+ tools organized into functional categories. Your AI assistant automatically discovers and uses these tools based on your prompts — you do not need to call them explicitly. Tools work best when combined. For example, to get a campaign performance report, the assistant will first call 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.
Most tools require a 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.
Always called at the start of each user turn, before using other SegmentStream tools. Pass the user’s message verbatim. Returns project context, relevant configuration, and an analytical approach tailored to the request. If status is clarify, the assistant resolves the ambiguity and calls again. If status is proceed, the assistant follows the returned approach.Parameters:
NameTypeRequiredDescription
user_promptstringYesThe user’s question or request, verbatim
user_intentstringNoWhat the user wants to achieve. Especially helpful when the message is short (“ok”, “yes”)
project_idstringNoOmit to auto-resolve
session_idstringNoSession ID from a previous analyze_request. Omit on first call
Returns: Project context, configuration details, and a step-by-step analytical approach.
Always called after completing work, before responding to the user. Pass the full draft response. Returns a quality assessment. If status is 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:
NameTypeRequiredDescription
response_draftstringYesThe full response planned for the user
feedbackstringNoProduct feedback: guidance gaps, tool issues, user friction. Logged for quality improvement, never shown to user
session_idstringYesSession ID returned by analyze_request
Returns: Quality assessment with status (approved or revise) and suggestions.
Load the report template, design system, and assets for building visual reports. Use format html if you can write files to disk, jsx if you render artifacts inline.Parameters:
NameTypeRequiredDescription
formatstringYesTemplate format: html (for file-based tools) or jsx (for inline rendering)
session_idstringYesSession ID returned by analyze_request
Returns: Report template, design system, and assets.Example prompts:
  • “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 all active SegmentStream projects with their id, name, timezone, type, account, and BigQuery configuration (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 details: name, timezone, currency, type, features, state, attributionAdjustment, maxAttributionWindow, workflowState, and billingAccount.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Full project configuration object.Example prompts:
  • “Show me the details of project X”
  • “What timezone and currency is this project configured with?”
  • “What features are enabled for this project?”
Create a new SegmentStream project with External BigQuery. Auto-resolves the billing account and creates a service account. Returns projectId and serviceAccountEmail.Parameters:
NameTypeRequiredDescription
project_namestringYesProject name, typically the website domain (e.g., example.com)
timezonestringYesIANA timezone identifier (e.g., Europe/London, America/New_York)
currencystringYesISO 4217 currency code (e.g., USD, EUR, GBP)
session_idstringYesSession ID returned by analyze_request
Returns: Object with 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 settings: name, timezone, or currency. Only pass the fields you want to change.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
project_namestringNoNew project name
timezonestringNoIANA timezone identifier
currencystringNoISO 4217 currency code
session_idstringYesSession ID returned by analyze_request
Returns: Updated project object.Example prompts:
  • “Change the project timezone to Europe/Berlin”
  • “Update the project currency to EUR”
  • “Rename the project to newsite.com”
Get the authenticated user’s profile: id, name, email, and role.Parameters:
NameTypeRequiredDescription
session_idstringYesSession ID returned by analyze_request
Returns: User profile object with id, name, email, and role.Example prompts:
  • “Who am I logged in as?”
  • “What role do I have?”
Get project members: id, name, email, role. Returns admins, viewers, and owners.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
Returns: Array of member objects with id, name, email, and role.Example prompts:
  • “Who has access to this project?”
  • “List all project members and their roles”
Invite a teammate to collaborate on a SegmentStream project. The teammate receives an email with context about what help is needed.Parameters:
NameTypeRequiredDescription
emailstringYesEmail address of the teammate to invite
project_idstringYesThe project ID to invite the teammate to
initial_promptstringYesContextual message explaining what help is needed
rolestringNoRole for the invited teammate: admin (default) or viewer
session_idstringYesSession ID returned by analyze_request
Returns: Confirmation of the invitation.Example prompts:
  • “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 all data sources for a SegmentStream project.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of data source objects.Example prompts:
  • “What ad platforms are connected to this project?”
  • “Show me all data sources”
  • “Which data sources are enabled?”
Get a single data source with details: id, name, type, isEnabled, isAuthenticated, options, authMeta, and workflow status.Parameters:
NameTypeRequiredDescription
data_source_idstringYesThe data source ID
session_idstringYesSession ID returned by analyze_request
Returns: Full data source configuration object.Example prompts:
  • “Show me the configuration of the Facebook data source”
  • “Is the Google Ads data source authenticated?”
Get import logs for a data source: phase, startedAt, fillDate, status, errors, and message.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
data_source_idstringYesThe data source ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of import log entries with phase, timestamps, status, and error details.Example prompts:
  • “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 all supported data source types with their display name, auth method (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 a data source to a project. Multi-step flow: call repeatedly — first returns an auth URL, then configuration fields, then connects. Pass options progressively as the user provides them.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
typestringYesData source type. Use display names: Google Analytics 4, Google Ads, Meta Ads, etc.
optionsobjectNoConfiguration options collected so far. Pass previous options plus the user’s selection for the next field
storage_preferencestringNoOnly for GA4 when no BigQuery Link exists: managed or bring_your_own
session_idstringYesSession ID returned by analyze_request
Returns: Next step in the connection flow (auth URL, configuration fields, or connection confirmation).Example prompts:
  • “Connect Google Ads to this project”
  • “Add Meta Ads as a data source”
  • “Set up a Google Analytics 4 connection”
Disconnect a data source by clearing its credentials. Resets it to unauthenticated state so you can reconnect via connect_data_source. Use when: wrong account selected, insufficient OAuth scopes, or broken connection state.Parameters:
NameTypeRequiredDescription
data_source_idstringYesThe ID of the data source to disconnect
session_idstringYesSession ID returned by analyze_request
Returns: Confirmation that credentials were cleared.Example prompts:
  • “Disconnect the Google Ads data source so I can reconnect with a different account”
  • “Reset the Facebook data source connection”
Connect BigQuery to a SegmentStream project. Progressive multi-step flow: may return configure (select GCP project, location, or dataset), grant_access (service account needs permissions), or connected (done). Pass selections back via parameters.Parameters:
NameTypeRequiredDescription
project_idstringYesSegmentStream project ID
gcp_project_idstringNoGoogle Cloud project ID where SegmentStream will store its BigQuery dataset
locationstringNoBigQuery dataset location (e.g., US, EU, us-central1). Should match the GA4 BigQuery export location if one exists
dataset_idstringNoBigQuery dataset ID for SegmentStream data. Defaults to segmentstream if omitted
session_idstringYesSession ID returned by analyze_request
Returns: Next step in the connection flow (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 all conversions for a project. Returns id, name, type (online_purchase, online_event, sql, combined, probabilistic), counting behavior, and key configuration.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of conversion objects.Example prompts:
  • “What conversions are configured in this project?”
  • “List all active conversions”
  • “Show me the conversion IDs I need for reporting”
Get a single conversion with full configuration including type (online_purchase/online_event/sql), counting behavior, matching conditions, custom SQL, audiences, and combined conversions.Parameters:
NameTypeRequiredDescription
conversion_idstringYesThe conversion ID
session_idstringYesSession ID returned by analyze_request
Returns: Full conversion configuration object.Example prompts:
  • “Show me how the Purchase conversion is configured”
  • “What matching conditions does this conversion use?”
  • “Show me the SQL for this custom conversion”
Create a conversion. Choose type based on data source: 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:
NameTypeRequiredDescription
project_idstringYesThe SegmentStream project ID
namestringYesConversion name (e.g., Purchase, Lead, Sign up)
typestringYesConversion type: online_purchase, online_event, or sql
matching_conditionsobjectNoRequired for online_event. Conditions defining which events count as this conversion
custom_sqlstringNoRequired for sql type. BigQuery SQL query defining the conversion
countingstringNoevery_occurrence (default) or once_per_user
counting_windownumberNoDays. Only used when counting is once_per_user (default 7)
value_typestringNonone (default), event_value, or fixed (online_event only)
valuenumberNoFixed conversion value. Only when value_type is fixed
adjustment_windownumberNoRefund adjustment window in days (online_purchase only)
session_idstringYesSession ID returned by analyze_request
Returns: Created conversion object.Example prompts:
  • “Create a Purchase conversion”
  • “Add a Sign Up conversion that tracks the sign_up event”
  • “Create a SQL conversion for CRM leads”
Update a conversion. Fetches current configuration and merges your changes. Only pass the fields you want to change. Works for all conversion types.Parameters:
NameTypeRequiredDescription
conversion_idstringYesThe conversion ID to update
namestringNoNew conversion name
matching_conditionsobjectNoUpdated matching conditions (online_event only)
custom_sqlstringNoUpdated SQL query (sql type only)
countingstringNoevery_occurrence or once_per_user
counting_windownumberNoDays. Only when counting is once_per_user
value_typestringNonone, event_value, or fixed (online_event only)
valuenumberNoFixed conversion value
descriptionstringNoConversion description
adjustment_windownumberNoRefund adjustment window in days (online_purchase only)
session_idstringYesSession ID returned by analyze_request
Returns: Updated conversion object.Example prompts:
  • “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 available fields for a specific conversion. Returns default fields (present on every conversion) and custom fields (CRM/dynamic — defined by the conversion SQL, vary per conversion). Use this before query_conversion_records to discover what data is available.Parameters:
NameTypeRequiredDescription
project_idstringYesThe SegmentStream project ID
conversion_idstringYesThe conversion ID to list fields for
session_idstringYesSession ID returned by analyze_request
Returns: Default and custom fields available for the conversion.Example prompts:
  • “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 including totalConversions, totalSessions, totalValues, visitors, conversionsHistory (per date), and exportsHistory.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
conversion_idstringYesThe conversion ID
date_fromstringNoStart date in YYYY-MM-DD format
date_tostringNoEnd date in YYYY-MM-DD format
chart_granularitystringNoDAY or HOUR
session_idstringYesSession ID returned by analyze_request
Returns: Statistics object with totals and per-date history.Example prompts:
  • “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 grouped by country for a given conversion and date range.Parameters:
NameTypeRequiredDescription
conversion_idstringYesThe conversion ID
project_idstringYesThe project ID
start_datestringYesStart date in YYYY-MM-DD format
end_datestringYesEnd date in YYYY-MM-DD format
session_idstringYesSession ID returned by analyze_request
Returns: Conversions grouped by country.Example prompts:
  • “Which countries had the most purchases last month?”
  • “Break down lead conversions by country for Q4”
Query individual conversion-level records. Returns one row per conversion event with selected fields — use for any question about specific customers, contacts, CRM data, or conversion-level attributes. Use 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:
NameTypeRequiredDescription
project_idstringYesThe SegmentStream project ID
conversion_idstringYesThe conversion ID to query records for
date_rangeobjectYesDate range with from and to in YYYY-MM-DD
fieldsarrayYesFields to return — use names from list_conversion_fields directly
attribution_idstringNoAttribution model ID — enables channel and campaign filtering
filterobjectNoFilter expression (same format as run_report)
order_byarrayNoSort order with field and direction
formatstringNojson (default) or csv for compact tabular output
limitnumberNoMax rows (default 500, max 1000)
offsetnumberNoRow offset for pagination
session_idstringYesSession ID returned by analyze_request
Returns: Individual conversion records with the requested fields.Example prompts:
  • “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 all attribution models for a project with their id, name, algorithm, attributionWindow, adjustment, filter, dimension, and isDisabled.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of attribution model objects.Example prompts:
  • “What attribution models are available?”
  • “Which attribution model is the default?”
  • “Show me all attribution model IDs”
Get a single attribution model with full details including calibration, dimension values, and self-reported attribution settings.Parameters:
NameTypeRequiredDescription
idstringYesThe attribution model ID
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Full attribution model configuration object.Example prompts:
  • “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 a new attribution model. After save, SegmentStream automatically runs a 1-year backfill to populate attribution data — no follow-up call needed. The window is capped by the project’s actual data.The 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:
NameTypeRequiredDescription
project_idstringYesThe project ID
namestringYesHuman-readable model name
algorithmstringYesfirst_click or last_click
attribution_windownumberNoWindow in days (default 90, null disables the cap)
significant_touch_ruleobjectNoBoolean filter AST, only valid for last_click. { and: [...] } | { or: [...] } | { option, operator, value }. Use list_filter_options for allowed option values
self_reported_reattributionbooleanNoWhether the model applies self-reported reattribution (default true)
session_idstringYesSession ID returned by analyze_request
Returns: Created attribution model in the same shape as 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 an attribution model. Supports partial updates of name, attribution window, significant-touch rule, and self-reported reattribution. After save, SegmentStream automatically reruns the 1-year backfill.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
idstringYesThe attribution model ID
namestringNoUpdated model name
attribution_windownumberNoUpdated window in days; null disables the cap
significant_touch_ruleobjectNoUpdated boolean filter AST (last-click only). Same shape as create_attribution_model
self_reported_reattributionbooleanNoToggle self-reported reattribution
session_idstringYesSession ID returned by analyze_request
Returns: Updated attribution model in the same shape as 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 an aggregated report query with proper attribution. Returns grouped metrics (conversions, ROAS, CPA, cost) by dimensions (channel, campaign, country). This is the primary tool for performance analytics. For individual conversion-level data, use 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:
NameTypeRequiredDescription
project_idstringYesThe project ID
saved_report_idstringNoIf provided, loads the saved report as the base; settings becomes a partial override
settingsobjectConditionalFull settings (when no saved_report_id) or override (when saved_report_id). See nested fields below
settings.date_rangeobjectConditionalPrimary date range. { interval, from, to }. interval defaults to custom; named intervals (last_7_days, last_30_days, etc.) resolve dates server-side
settings.comparison_date_rangeobjectNoComparison date range for period-over-period analysis. Supports relative intervals (preceding_period, same_period_last_year)
settings.dimensionsarray of stringNoDimensions to group by (campaign_name, ad_platform, channel, country, etc.). channel is a built-in alias for the Channel grouped dimension
settings.metricsarray of stringNoBare snake_case metric names — server infers traffic vs. conversion. Traffic: cost, clicks, impressions, sessions, users, cpc, cpm, ctr. Conversion: conversions, conversion_value, converted_users, conversion_rate, cpa, roas, aov, plus *_by_conv_time and *_incl_projected variants. Never prefix with the AC id — pass once and it fans out to every entry in attributed_conversions
settings.attributed_conversionsarrayConditional[{ id, conversion_id, attribution_id }]. Required when conversion metrics are requested. Per-AC output columns are named <id>:<metric>
settings.filterobjectNoFilter expression. Boolean AST: { and: [...] } | { or: [...] } | { option, operator, value }. Operators: equals, not_equals, contains, not_contains, in, not_in, gt, gte, lt, lte, is_set, not_set
settings.order_byarrayNo[{ metric, direction, scope?, attributed_conversion_id? }]. scope (first_interval/second_interval/diff) is only meaningful with a comparison date range
limitnumberNoMax rows (default 1000, max 1000)
offsetnumberNoRow offset for pagination
time_machine_datestringNoYYYY-MM-DD snapshot of tracked conversions and ML predictions as of that date. Must be a Sunday for projections
formatstringNojson (default) or csv
session_idstringYesSession ID returned by analyze_request
Returns: Table data with dimensions and metrics for each row, plus totals (and 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 a timeseries (chart) report — per-date metric values over a date range. Useful for visualizing trends and spotting anomalies. To run the timeseries view of a saved report, pass saved_report_id; the saved chart config (chart.date_granularity, chart.metrics) becomes the base and settings is a partial override.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
saved_report_idstringNoIf provided, loads the saved report’s chart config as the base
settingsobjectConditionalSame nested shape as run_report settings (no comparison_date_range) plus a nested chart sub-object
settings.date_rangeobjectConditional{ interval, from, to }
settings.dimensionsarray of stringNoDimensions to group by
settings.attributed_conversionsarrayConditionalRequired when conversion metrics are plotted
settings.filterobjectNoFilter expression — same shape as run_report
settings.chart.date_granularitystringNoday (default), hour, week, or month
settings.chart.metricsarrayNoMetrics to plot. Bare strings or { metric, attributed_conversion_id } entries pinned to a specific AC
time_machine_datestringNoYYYY-MM-DD snapshot date
session_idstringYesSession ID returned by analyze_request
Returns: Per-date data points for the requested metrics.Example prompts:
  • “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 all saved reports for a project, each with full settings (dimensions, metrics, filter, date range, chart config). Match user intent against name + settings in place — no second fetch needed. When an entry matches, run it via run_report (or run_report_timeseries) with saved_report_id.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of saved reports, each with 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 a single saved report by id. Returns id, name, project_id, url (admin panel link), and settings — date range, dimensions, metrics, attributed_conversions, filter, order_by, chart config. The returned settings can be passed directly to 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:
NameTypeRequiredDescription
project_idstringYesThe project ID
report_idstringYesThe saved report ID
session_idstringYesSession ID returned by analyze_request
Returns: Full saved report (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?”
Create, update, or duplicate a saved report. Upsert semantics — omit 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:
NameTypeRequiredDescription
project_idstringYesThe project ID
idstringNoExisting report id to update. Omit to create.
namestringYesHuman-readable report name
settingsobjectYesFull report settings — same shape as get_saved_report returns. Includes date_range, dimensions, metrics, attributed_conversions, filter, order_by, optional chart, optional percentage_metrics / percentage_difference_metrics
session_idstringNoSession ID returned by analyze_request
Returns: Saved report with 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”
Upload an HTML artifact to shared storage and return a shareable URL. Use for sharing reports, dashboards, and analysis results.Parameters:
NameTypeRequiredDescription
html_contentstringYesThe full HTML content of the artifact to share
titlestringYesHuman-readable title for the artifact
session_idstringYesSession ID returned by analyze_request
Returns: Shareable URL for the uploaded artifact.Example prompts:
  • “Share this report as a link”
  • “Generate a shareable URL for this dashboard”

​
Filters

Tools for discovering valid filter fields and their values. Used before building filter expressions for run_report, query_conversion_records, conversion matching conditions, grouped dimension rules, and attribution model significant-touch rules.
List available filter fields for a specific tool. Pass the tool name that needs filters — the response includes only fields valid for that tool.
  • 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.).
Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
toolstringYesWhich tool needs filter options (e.g. run_report, create_conversion, create_grouped_dimension)
Returns: Array of filter field definitions appropriate for the requested tool.Example prompts:
  • “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 distinct values for a filter option. Pass the tool name and field — returns actual values from the project data. Use after 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).
Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
toolstringYesWhich tool needs these values (determines the data source to query)
fieldstringYesThe field to query values for (e.g. campaign_name, ad_platform, country, event.name, channel, or a custom_dimension_* key)
querystringNoSubstring filter (case-insensitive). Pass ONE keyword
Returns: Array of available values for the specified field.Example prompts:
  • “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.
Query the user journey for a date range, returning all sessions with attribution credits, conversions, audience memberships, and user keys. Filter by anonymous_id or user_id. Useful for debugging attribution and understanding individual user paths.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
params.date_fromstringYesStart date (YYYY-MM-DD)
params.date_tostringYesEnd date (YYYY-MM-DD)
params.attributed_conversionsarrayYesArray of {id, conversion_id, attribution_id} objects
params.conversion_internal_idsarrayYesConversion internal IDs to include
params.selected_anonymous_idstringNoFilter to a specific anonymous ID
params.selected_user_idstringNoFilter to a specific user ID
session_idstringYesSession ID returned by analyze_request
Returns: Sessions with attribution credits, conversions, audience memberships, and user keys.Example prompts:
  • “Show me the user journey for anonymous ID abc123 over 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”
Get the generated BigQuery SQL and query parameters for a user journey query without executing it. Useful for debugging attribution SQL.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
paramsobjectYesSame parameters as get_user_journey
session_idstringYesSession ID returned by analyze_request
Returns: BigQuery SQL string and query parameters.Example prompts:
  • “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 — use run_report, query_conversion_records, and query_filter_option_values instead.
Execute a read-only BigQuery SQL query against the project’s dataset. Tables can be referenced without full qualification (e.g., 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:
NameTypeRequiredDescription
project_idstringYesThe SegmentStream project ID (use list_active_projects to find it)
querystringYesThe BigQuery SQL query to execute. Tables can be referenced without full qualification
session_idstringYesSession ID returned by analyze_request
Returns: Query results as JSON.Example prompts:
  • “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?”
Get the schema (column names, types, modes) of a BigQuery table via the API — no SQL needed. Use this before writing SQL queries to verify table structure and available columns. Returns null if the table does not exist. Use list_active_projects to find the project ID.Parameters:
NameTypeRequiredDescription
project_idstringYesThe SegmentStream project ID
table_namestringYesThe table name within the project dataset (e.g., hitsSet, conversions, attribution, cost_data). Do not fully qualify — the project dataset is used automatically
session_idstringYesSession ID returned by analyze_request
Returns: Array of column objects with name, type, and mode.Example prompts:
  • “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 all grouped dimensions for a project. Use the key in run_report dimensions or get_grouped_dimension. channel is a built-in alias for the Channel dimension.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of grouped dimension objects with key, name, and type.Example prompts:
  • “What grouped dimensions are available?”
  • “List all dimension keys I can use in reports”
Get a grouped dimension with its groups and filter rules. Use key 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:
NameTypeRequiredDescription
project_idstringYesThe project ID
keystringYesThe grouped dimension key (e.g. channel)
session_idstringYesSession ID returned by analyze_request
Returns: Full grouped dimension object with groups and filters.Example prompts:
  • “Show me the Channel dimension groups”
  • “How is this grouped dimension configured?”
Create a new grouped dimension. Groups categorize traffic by assigning base dimension values to named buckets. Filters use base dimensions only (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:
NameTypeRequiredDescription
project_idstringYesThe project ID
namestringYesDisplay name for the new dimension (e.g. Region, Product Category)
groupsarrayNoEach group has a name and filter. Groups are evaluated in order — first match wins. Traffic not matching any group falls into the auto-appended Other group
session_idstringYesSession ID returned by analyze_request
Returns: Object with 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 a grouped dimension. For the Channel dimension (key 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" }] }.
Full replacement — groups not included are permanently removed. Call get_grouped_dimension first to see current groups.
Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
keystringYesGrouped dimension key. Use channel for the Channel dimension
namestringNoNew display name for the dimension
groupsarrayNoGroup definitions, evaluated in order. Each group has a name and filter (same boolean AST as run_report filters). Use query_filter_option_values to discover exact values
session_idstringYesSession ID returned by analyze_request
Returns: Object with 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 for a project, optionally filtered by ML model or conversion. Returns id, name, isForever, filter, membershipDurationDays, and status for each audience.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
ml_model_idstringNoFilter audiences by ML model
conversion_idstringNoFilter audiences by conversion
session_idstringYesSession ID returned by analyze_request
Returns: Array of audience objects.Example prompts:
  • “What audiences are defined in this project?”
  • “List all audiences associated with the Purchase conversion”
Get a single audience with full details including id, name, projectId, isForever, filter, filterSql, membershipDurationDays, status, createdAt, and updatedAt.Parameters:
NameTypeRequiredDescription
audience_idstringYesThe audience ID
session_idstringYesSession ID returned by analyze_request
Returns: Full audience configuration object.Example prompts:
  • “Show me the filter criteria for this audience”
  • “How long do users stay in this audience?”
Query audience memberships for a specific client (anonymous ID) within a date range. Returns audienceId, audienceName, entryTime, and expirationTime for each membership.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
anonymous_idstringYesThe anonymous client ID to query audience memberships for
fromstringYesStart date (ISO date, e.g., 2025-01-01)
tostringYesEnd date (ISO date, e.g., 2025-01-31)
session_idstringYesSession ID returned by analyze_request
Returns: Array of audience membership objects with entry and expiration times.Example prompts:
  • “What audiences does anonymous ID abc123 belong to?”
  • “Show me audience memberships for this user over the last 30 days”
Get audience inclusion statistics for a project: per-audience inclusion count and percent, total inclusion, total percent, and allUsers count. Optionally filter by ML model.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
ml_model_idstringNoFilter inclusion stats by ML model
session_idstringYesSession ID returned by analyze_request
Returns: Inclusion statistics with per-audience counts and percentages.Example prompts:
  • “What percentage of users are in each audience?”
  • “Show me audience inclusion statistics”

​
Workflows

Tools for monitoring data processing workflows.
List recent workflows for a SegmentStream project.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
limitnumberNoMaximum number of workflows to return (default 20)
session_idstringYesSession ID returned by analyze_request
Returns: Array of workflow objects.Example prompts:
  • “Show me the recent workflows”
  • “What data processing jobs ran today?”
Get the status and details of a specific workflow, including data source logs and errors.Parameters:
NameTypeRequiredDescription
workflow_idstringYesThe workflow ID
session_idstringYesSession ID returned by analyze_request
Returns: Workflow status object with data source logs and error details.Example prompts:
  • “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 metrics: quality scores (total, 7-day, 1-day) and histogram. Optionally filter by data source and date range.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
data_source_idnumberNoScope results to a specific data source
date_fromstringNoStart date (YYYY-MM-DD)
date_tostringNoEnd date (YYYY-MM-DD)
session_idstringYesSession ID returned by analyze_request
Returns: Quality scores and histogram data.Example prompts:
  • “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 including user stitching distribution, key combinations, and data completeness.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
conversion_internal_idstringNoFilter by internal conversion ID
days_backnumberNoNumber of days to look back
use_users_v2booleanNoWhether to use the users v2 engine
session_idstringYesSession ID returned by analyze_request
Returns: Identity graph statistics object.Example prompts:
  • “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 for a project with optional filtering by status and pagination.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
statusstringNoFilter by status: Ok or Error
limitnumberNoMaximum number of incidents to return
offsetnumberNoNumber of incidents to skip for pagination
minimum_updated_atstringNoOnly return incidents updated after this ISO-8601 date
session_idstringYesSession ID returned by analyze_request
Returns: Array of incident objects.Example prompts:
  • “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 all classifiers for a project with their configuration.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of classifier objects.Example prompts:
  • “What ML classifiers are configured?”
  • “Show me the classifier settings for this project”
Get a single classifier with full configuration.Parameters:
NameTypeRequiredDescription
classifier_idstringYesThe classifier ID
session_idstringYesSession ID returned by analyze_request
Returns: Full classifier configuration object.Example prompts:
  • “Show me the details of this classifier”
  • “What model does this classifier use?”
List available classifier models with pricing information.Parameters:
NameTypeRequiredDescription
session_idstringYesSession ID returned by analyze_request
Returns: Array of available classifier model types with pricing.Example prompts:
  • “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 all portfolios for a project with their id, name, goal, granularity, hidden status, metrics (potentialMetric, actualMetric, actualSpend), targetsCount, isReady, and lastApplyTime.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of portfolio objects with configuration and summary metrics.Example prompts:
  • “What portfolios are configured in this project?”
  • “List all optimization portfolios”
  • “Which portfolios are ready for optimization?”
Get portfolio performance history. When called with only 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:
NameTypeRequiredDescription
portfolio_idstringYesThe portfolio ID
periodstringNoHistory period: LAST_MONTH, LAST_THREE_MONTHS (default), or LAST_SIX_MONTHS
start_datestringNoPeriod start date (ISO-8601, e.g., 2025-01-01). When provided with end_date, returns detailed per-campaign breakdowns
end_datestringNoPeriod end date (ISO-8601, e.g., 2025-01-31). When provided with start_date, returns detailed per-campaign breakdowns
session_idstringYesSession ID returned by analyze_request
Returns: Performance history with per-period metrics and optional per-campaign detail.Example prompts:
  • “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 data from the Optimize tab: current scenario, per-target optimization results with marginal metrics, diminishing return curves, and optional maturation/projection data.Parameters:
NameTypeRequiredDescription
portfolio_idstringYesThe portfolio ID
total_budget_limitnumberNoTotal budget constraint for the optimization period
total_daily_budget_limitnumberNoDaily budget constraint for optimization
optimization_versionstringNoOptimization algorithm version (default: v7)
session_idstringYesSession ID returned by analyze_request
Returns: Optimization scenario with per-target results, marginal metrics, and diminishing return curves.Example prompts:
  • “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 all experiments for a project with their status, preparation, and analysis results.Parameters:
NameTypeRequiredDescription
project_idstringYesThe project ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of experiment objects with status and results.Example prompts:
  • “What experiments are running?”
  • “Show me all geo tests and their status”
  • “List completed experiments with their results”
Get a single experiment with full details including plots, preparation, and analysis results.Parameters:
NameTypeRequiredDescription
experiment_idstringYesThe experiment ID
session_idstringYesSession ID returned by analyze_request
Returns: Full experiment object with plots, preparation data, and analysis results.Example prompts:
  • “Show me the results of this geo test”
  • “What was the measured lift in this experiment?”
  • “Show me the experiment preparation details”
Get available custom parameter keys for market-split experiments.Parameters:
NameTypeRequiredDescription
conversion_idstringYesThe conversion ID
session_idstringYesSession ID returned by analyze_request
Returns: Array of custom parameter keys.Example prompts:
  • “What custom parameters can I use for geo test segmentation?”
  • “List available custom parameter keys for experiments”