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.analyze_request
analyze_request
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
Returns: Project context, configuration details, and a step-by-step analytical approach.
clarify, the assistant resolves the ambiguity and calls again. If status is proceed, the assistant follows the returned approach.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
user_prompt | string | Yes | The user’s question or request, verbatim |
project_id | string | No | Omit to auto-resolve |
session_id | string | No | Session ID from a previous analyze_request. Omit on first call |
analyze_response
analyze_response
Always called after completing work, before responding to the user. Pass the full draft response. Returns a quality assessment. If status is
Returns: Quality assessment with status (
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:| Name | Type | Required | Description |
|---|---|---|---|
response_draft | string | Yes | The full response planned for the user |
feedback | string | No | Product feedback: guidance gaps, tool issues, user friction. Logged for quality improvement, never shown to user |
session_id | string | Yes | Session ID returned by analyze_request |
approved or revise) and suggestions.Projects and account
Tools for creating, managing, and inspecting projects and user accounts.list_active_projects
list_active_projects
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
get_project
Get project details: name, timezone, currency, type, features, state,
Returns: Full project configuration object.Example prompts:
attributionAdjustment, maxAttributionWindow, workflowState, and billingAccount.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Create a new SegmentStream project with External BigQuery. Auto-resolves the billing account and creates a service account. Returns
Returns: Object with
projectId and serviceAccountEmail.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_name | string | Yes | Project name, typically the website domain (e.g., example.com) |
timezone | string | Yes | IANA timezone identifier (e.g., Europe/London, America/New_York) |
currency | string | Yes | ISO 4217 currency code (e.g., USD, EUR, GBP) |
session_id | string | Yes | Session ID returned by analyze_request |
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
Update project settings: name, timezone, or currency. Only pass the fields you want to change.Parameters:
Returns: Updated project object.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
project_name | string | No | New project name |
timezone | string | No | IANA timezone identifier |
currency | string | No | ISO 4217 currency code |
session_id | string | Yes | Session ID returned by analyze_request |
- “Change the project timezone to Europe/Berlin”
- “Update the project currency to EUR”
- “Rename the project to newsite.com”
project_setup
project_setup
Set up a new SegmentStream project or continue onboarding an existing one. Returns the current onboarding step and instructions. If setup is already complete, says so.Parameters:
Returns: Current onboarding step and instructions.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID returned by analyze_request |
- “Help me set up SegmentStream”
- “Continue onboarding my project”
- “What’s the next setup step?”
get_current_user
get_current_user
Get the authenticated user’s profile: id, name, email, and role.Parameters:
Returns: User profile object with id, name, email, and role.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID returned by analyze_request |
- “Who am I logged in as?”
- “What role do I have?”
get_project_members
get_project_members
Get project members: id, name, email, role. Returns admins, viewers, and owners.Parameters:
Returns: Array of member objects with id, name, email, and role.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
- “Who has access to this project?”
- “List all project members and their roles”
invite_teammate
invite_teammate
Invite a teammate to collaborate on a SegmentStream project. The teammate receives an email with context about what help is needed.Parameters:
Returns: Confirmation of the invitation.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address of the teammate to invite |
project_id | string | Yes | The project ID to invite the teammate to |
initial_prompt | string | Yes | Contextual message explaining what help is needed |
role | string | No | Role for the invited teammate: admin (default) or viewer |
session_id | string | Yes | Session ID returned by analyze_request |
- “Invite [email protected] to help connect BigQuery”
- “Add my colleague as a viewer on this project”
invite_to_research_preview
invite_to_research_preview
Invite a user to SegmentStream research preview by email. Sends an invitation link. SuperAdmin only.Parameters:
Returns: Invitation confirmation or signup link.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to invite |
send_email | boolean | No | Send invitation email (default true). Set to false to just get the signup link |
- “Invite [email protected] to the research preview”
- “Generate a signup link for this email”
Data sources
Tools for connecting, inspecting, and managing advertising platforms and their import status.list_data_sources
list_data_sources
List all data sources for a SegmentStream project.Parameters:
Returns: Array of data source objects.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What ad platforms are connected to this project?”
- “Show me all data sources”
- “Which data sources are enabled?”
get_data_source
get_data_source
Get a single data source with details: id, name, type,
Returns: Full data source configuration object.Example prompts:
isEnabled, isAuthenticated, options, authMeta, and workflow status.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
data_source_id | string | Yes | The data source ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “Show me the configuration of the Facebook data source”
- “Is the Google Ads data source authenticated?”
get_data_source_logs
get_data_source_logs
Get import logs for a data source: phase,
Returns: Array of import log entries with phase, timestamps, status, and error details.Example prompts:
startedAt, fillDate, status, errors, and message.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
data_source_id | string | Yes | The data source ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
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_data_source
connect_data_source
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:
Returns: Next step in the connection flow (auth URL, configuration fields, or connection confirmation).Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
type | string | Yes | Data source type. Use display names: Google Analytics 4, Google Ads, Meta Ads, etc. |
options | object | No | Configuration options collected so far. Pass previous options plus the user’s selection for the next field |
storage_preference | string | No | Only for GA4 when no BigQuery Link exists: managed or bring_your_own |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Disconnect a data source by clearing its credentials. Resets it to unauthenticated state so you can reconnect via
Returns: Confirmation that credentials were cleared.Example prompts:
connect_data_source. Use when: wrong account selected, insufficient OAuth scopes, or broken connection state.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
data_source_id | string | Yes | The ID of the data source to disconnect |
session_id | string | Yes | Session ID returned by analyze_request |
- “Disconnect the Google Ads data source so I can reconnect with a different account”
- “Reset the Facebook data source connection”
connect_bigquery
connect_bigquery
Connect BigQuery to a SegmentStream project. Progressive multi-step flow: may return
Returns: Next step in the connection flow (
configure (select GCP project, location, or dataset), grant_access (service account needs permissions), or connected (done). Pass selections back via parameters.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | SegmentStream project ID |
gcp_project_id | string | No | Google Cloud project ID where SegmentStream will store its BigQuery dataset |
location | string | No | BigQuery dataset location (e.g., US, EU, us-central1). Should match the GA4 BigQuery export location if one exists |
dataset_id | string | No | BigQuery dataset ID for SegmentStream data. Defaults to segmentstream if omitted |
session_id | string | Yes | Session ID returned by analyze_request |
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
List all conversions for a project. Returns id, name, type (
Returns: Array of conversion objects.Example prompts:
online_purchase, online_event, sql, combined, probabilistic), counting behavior, and key configuration.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What conversions are configured in this project?”
- “List all active conversions”
- “Show me the conversion IDs I need for reporting”
get_conversion
get_conversion
Get a single conversion with full configuration including type (
Returns: Full conversion configuration object.Example prompts:
online_purchase/online_event/sql), counting behavior, matching conditions, custom SQL, audiences, and combined conversions.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
conversion_id | string | Yes | The conversion ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Create a conversion. Choose type based on data source:
Returns: Created conversion object.Example prompts:
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 query_dimension_values with custom_field to discover available values.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The SegmentStream project ID |
name | string | Yes | Conversion name (e.g., Purchase, Lead, Sign up) |
type | string | Yes | Conversion type: online_purchase, online_event, or sql |
matching_conditions | object | No | Required for online_event. Conditions defining which events count as this conversion |
custom_sql | string | No | Required for sql type. BigQuery SQL query defining the conversion |
counting | string | No | every_occurrence (default) or once_per_user |
counting_window | number | No | Days. Only used when counting is once_per_user (default 7) |
value_type | string | No | none (default), event_value, or fixed (online_event only) |
value | number | No | Fixed conversion value. Only when value_type is fixed |
adjustment_window | number | No | Refund adjustment window in days (online_purchase only) |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Update a conversion. Fetches current configuration and merges your changes. Only pass the fields you want to change. Works for all conversion types.Parameters:
Returns: Updated conversion object.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
conversion_id | string | Yes | The conversion ID to update |
name | string | No | New conversion name |
matching_conditions | object | No | Updated matching conditions (online_event only) |
custom_sql | string | No | Updated SQL query (sql type only) |
counting | string | No | every_occurrence or once_per_user |
counting_window | number | No | Days. Only when counting is once_per_user |
value_type | string | No | none, event_value, or fixed (online_event only) |
value | number | No | Fixed conversion value |
description | string | No | Conversion description |
adjustment_window | number | No | Refund adjustment window in days (online_purchase only) |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
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
Returns: Default and custom fields available for the conversion.Example prompts:
query_conversion_records to discover what data is available.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The SegmentStream project ID |
conversion_id | string | Yes | The conversion ID to list fields for |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get conversion statistics including
Returns: Statistics object with totals and per-date history.Example prompts:
totalConversions, totalSessions, totalValues, visitors, conversionsHistory (per date), and exportsHistory.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
conversion_id | string | Yes | The conversion ID |
date_from | string | No | Start date in YYYY-MM-DD format |
date_to | string | No | End date in YYYY-MM-DD format |
chart_granularity | string | No | DAY or HOUR |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get conversions grouped by country for a given conversion and date range.Parameters:
Returns: Conversions grouped by country.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
conversion_id | string | Yes | The conversion ID |
project_id | string | Yes | The project ID |
start_date | string | Yes | Start date in YYYY-MM-DD format |
end_date | string | Yes | End date in YYYY-MM-DD format |
session_id | string | Yes | Session ID returned by analyze_request |
- “Which countries had the most purchases last month?”
- “Break down lead conversions by country for Q4”
query_conversion_records
query_conversion_records
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
Returns: Individual conversion records with the requested fields.Example prompts:
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:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The SegmentStream project ID |
conversion_id | string | Yes | The conversion ID to query records for |
date_range | object | Yes | Date range with from and to in YYYY-MM-DD |
fields | array | Yes | Fields to return — use names from list_conversion_fields directly |
attribution_id | string | No | Attribution model ID — enables channel and campaign filtering |
filter | object | No | Filter expression (same format as run_report) |
order_by | array | No | Sort order with field and direction |
format | string | No | json (default) or csv for compact tabular output |
limit | number | No | Max rows (default 500, max 1000) |
offset | number | No | Row offset for pagination |
session_id | string | Yes | Session ID returned by analyze_request |
- “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 attribution model configurations.list_attribution_models
list_attribution_models
List all attribution models for a project with their id, name, algorithm,
Returns: Array of attribution model objects.Example prompts:
attributionWindow, adjustment, filter, dimension, and isDisabled.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What attribution models are available?”
- “Which attribution model is the default?”
- “Show me all attribution model IDs”
get_attribution_model
get_attribution_model
Get a single attribution model with full details including calibration, dimension values, and self-reported attribution settings.Parameters:
Returns: Full attribution model configuration object.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The attribution model ID |
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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?”
Reports and analytics
Tools for querying campaign performance data — the primary way to pull metrics from SegmentStream.run_report
run_report
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 (customer emails, CRM fields), use
Returns: Table data with dimensions and metrics for each row, plus totals.Example prompts:
query_conversion_records instead. Use query_dimension_values to discover exact filter values. Use format: "csv" for fewer tokens.Supports 30+ built-in dimensions (campaign_name, ad_platform, country, source_medium, date, etc.) plus custom dimensions. Metrics are passed as a single unified list — the server automatically determines whether each metric is a traffic metric or a conversion metric.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
format | string | No | Response format: json (default) or csv. Use csv for a compact tabular representation |
params.date_range | object | Yes | Primary date range with from and to in YYYY-MM-DD |
params.comparison_date_range | object | No | Comparison date range for period-over-period analysis |
params.dimensions | array | No | Dimensions to group by (e.g., campaign_name, ad_platform, channel, anonymous_id). channel is a built-in alias for the Channel custom dimension. Use list_custom_dimensions to discover other custom dimensions |
params.metrics | array | No | Metrics to return. Traffic: clicks, cost, impressions, sessions, users, cpc, cpm, ctr, avg_session_duration, time_on_site, video_views, video_view_rate. Conversion: conversions, conversion_value, converted_users, conversion_rate, cpa, roas, aov, and _by_conv_time / _incl_projected variants. Server infers metric type automatically |
params.attributed_conversions | array | No | Array of {id, conversion_id, attribution_id} objects — required when conversion metrics are requested |
params.filter | object | No | Filter expression with dimension, operator, and value — supports and/or combinators. Binary operators: equals, not_equals, contains, not_contains, in, not_in, gt, gte, lt, lte. Unary operators: is_set, not_set |
params.order_by | array | No | Sort order. Each item has metric, direction (asc/desc), optional attributed_conversion_id and scope |
params.limit | number | No | Max rows (default 1000, max 1000) |
params.offset | number | No | Row offset for pagination |
params.time_machine_date | string | No | Time machine date (YYYY-MM-DD, must be a Sunday) — snapshot of tracked conversions and ML predictions as of that date |
session_id | string | Yes | Session ID returned by analyze_request |
- “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_report_timeseries
run_report_timeseries
Run a timeseries report: per-date attribution metrics, conversion metrics, and calculated metrics over a date range. Useful for visualizing trends over time and spotting anomalies.Parameters:
Returns: Per-date data points for the requested metrics.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
params.date_range | object | Yes | Date range with from and to in YYYY-MM-DD |
params.granularity | string | No | day (default), hour, week, or month |
params.metrics | array | No | Metrics to return (same as run_report) |
params.attributed_conversions | array | No | Conversion + attribution model pairs. Required when conversion metrics are requested |
params.filter | object | No | Filter expression |
params.time_machine_date | string | No | Time machine date (YYYY-MM-DD, must be a Sunday) |
session_id | string | Yes | Session ID returned by analyze_request |
- “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”
run_saved_report
run_saved_report
Run a saved report config by ID. Loads the config settings (dimensions, metrics, filters, ordering) and executes the query. Optionally override the date range, filter, or sort order. Use
Returns: Table data with dimensions and metrics, using the saved config settings plus any overrides.Example prompts:
list_report_configs to find config IDs.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
config_id | string | Yes | The saved report config ID (from list_report_configs) |
date_range | object | No | Override the saved date range. If omitted, uses the config’s firstDateRange |
filter | object | No | Override the saved filter. If omitted, uses the config’s filter (if any) |
order_by | array | No | Override the saved sort order. If omitted, uses the config’s ordering |
format | string | No | Response format: json (default) or csv |
limit | number | No | Max rows (default 1000, max 1000) |
offset | number | No | Row offset for pagination |
session_id | string | Yes | Session ID returned by analyze_request |
- “Run the Performance Overview report for last month”
- “Execute the saved channel report but filter by Google Ads only”
- “Run report config X with a custom date range”
list_report_configs
list_report_configs
List all report configurations for a project. Returns id, name, and order for each report. Use
Returns: Array of report configuration summaries.Example prompts:
get_report_config to fetch full settings for a specific report.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What reports are saved in this project?”
- “List all report configurations”
get_report_config
get_report_config
Get a single report configuration with full settings: date ranges, dimensions, attribution/conversion metrics, filters, ordering, and chart config.Parameters:
Returns: Full report configuration object.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
report_id | string | Yes | The report config ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “Show me the configuration of the Performance Overview report”
- “What dimensions and metrics does this report use?”
query_dimension_values
query_dimension_values
Discover available values for any dimension or field. Essential before building filters for
Returns: Array of available values for the specified dimension.Example prompts:
run_report, create_conversion matching conditions, or create_custom_dimension group rules. Provide one of: common_dimension (e.g., campaign_name, ad_platform, country), custom_dimension_key, or custom_field for hit-level fields (e.g., event.name, event.page.url). Use query to search by substring.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
common_dimension | string | No | Built-in dimension name: account_id, account_name, ad_group_id, ad_group_name, ad_id, ad_name, ad_platform, anonymous_id, campaign_id, campaign_name, campaign_type, channel, city, country, data_source_id, date, device, device_brand, domain, landing_page, landing_page_path, region, source_medium, targeting_id, targeting_name, user_id, utm_campaign, utm_content, utm_medium, utm_source, utm_term |
custom_dimension_key | string | No | Custom dimension key — returns group names for that dimension |
custom_field | string | No | Custom field name (e.g., event.name) |
custom_field_scope | string | No | Custom field scope (table name) |
query | string | No | Substring filter (case-insensitive). Pass one keyword, not a phrase |
session_id | string | Yes | Session ID returned by analyze_request |
- “What campaign names are available for filtering?”
- “List all ad platform values in this project”
- “What values are available for the source_medium dimension?”
export_report_csv
export_report_csv
Enqueue a CSV export for a report. Returns a job ID that can be polled with
Returns: Job ID for polling with
get_download_job (type: csv-v4) to obtain the download URL once the export is ready.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
params | object | Yes | Same parameters as run_report |
report_name | string | No | Human-readable report name for the CSV file |
billing_account_name | string | No | Billing account name to include in the CSV |
interval | string | No | Date interval shorthand: custom, last_7_days, last_14_days, last_28_days, last_30_days, last_60_days, last_90_days, last_6_months, last_12_months, yesterday |
session_id | string | Yes | Session ID returned by analyze_request |
get_download_job.Example prompts:- “Export this report as a CSV”
- “Download campaign performance data for the last quarter”
get_download_job
get_download_job
Poll the status of a download job (CSV or Google Sheets export). Returns progress (0—100), status, download URL (when completed), and failure reason (when failed).Parameters:
Returns: Job status object with
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
job_id | string | Yes | Job ID returned by export_report_csv |
type | string | Yes | Job type: csv-v4 or google-sheets-v4 |
session_id | string | Yes | Session ID returned by analyze_request |
progress (0—100), status (waiting, active, completed, failed), download URL, and failedReason.Example prompts:- “Is my CSV export ready?”
- “Check the status of the download job”
preview_report_sql
preview_report_sql
Preview the generated BigQuery SQL for a report query without executing it. Returns the SQL query string and resolved attributed conversions JSON. Useful for debugging report queries.Parameters:
Returns: Object with
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
params | object | Yes | Same parameters as run_report |
session_id | string | Yes | Session ID returned by analyze_request |
sqlQueryString and attributed conversions JSON.Example prompts:- “Show me the SQL that would be generated for this report”
- “What BigQuery query does SegmentStream run for campaign performance?”
get_report_template
get_report_template
Load the report template, design system, and assets for building visual reports. Use format
Returns: Report template, design system, and assets.Example prompts:
html if you can write files to disk, jsx if you render artifacts inline.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
format | string | Yes | Template format: html (for file-based tools) or jsx (for inline rendering) |
session_id | string | Yes | Session ID returned by analyze_request |
- “Build me a visual report for last month’s performance”
- “Create a branded dashboard with the report template”
share_artifact
share_artifact
User journey
Tools for tracing individual user paths and attribution credit distribution.get_user_journey
get_user_journey
Query the user journey for a date range, returning all sessions with attribution credits, conversions, audience memberships, and user keys. Filter by
Returns: Sessions with attribution credits, conversions, audience memberships, and user keys.Example prompts:
anonymous_id or user_id. Useful for debugging attribution and understanding individual user paths.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
params.date_from | string | Yes | Start date (YYYY-MM-DD) |
params.date_to | string | Yes | End date (YYYY-MM-DD) |
params.attributed_conversions | array | Yes | Array of {id, conversion_id, attribution_id} objects |
params.conversion_internal_ids | array | Yes | Conversion internal IDs to include |
params.selected_anonymous_id | string | No | Filter to a specific anonymous ID |
params.selected_user_id | string | No | Filter to a specific user ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get the generated BigQuery SQL and query parameters for a user journey query without executing it. Useful for debugging attribution SQL.Parameters:
Returns: BigQuery SQL string and query parameters.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
params | object | Yes | Same parameters as get_user_journey |
session_id | string | Yes | Session ID returned by analyze_request |
- “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_dimension_values instead.
bigquery_execute_sql
bigquery_execute_sql
Execute a read-only BigQuery SQL query against the project’s dataset. Tables can be referenced without full qualification (e.g.,
Returns: Query results as JSON.Example prompts:
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:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The SegmentStream project ID (use list_active_projects to find it) |
query | string | Yes | The BigQuery SQL query to execute. Tables can be referenced without full qualification |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
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
Returns: Array of column objects with name, type, and mode.Example prompts:
null if the table does not exist. Use list_active_projects to find the project ID.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The SegmentStream project ID |
table_name | string | Yes | The table name within the project dataset (e.g., hitsSet, conversions, attribution, cost_data). Do not fully qualify — the project dataset is used automatically |
session_id | string | Yes | Session ID returned by analyze_request |
- “What columns does the sessions table have?”
- “Show me the schema for hitsSet”
- “What fields are available in the conversions table?”
Custom dimensions
Tools for creating, updating, and inspecting custom dimensions configured in your project.list_custom_dimensions
list_custom_dimensions
List all custom dimensions for a project. Use the key in
Returns: Array of custom dimension objects with key, name, and type.Example prompts:
run_report dimensions or get_custom_dimension. channel is a built-in alias for the Channel dimension.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What custom dimensions are available?”
- “List all custom dimension keys I can use in reports”
get_custom_dimension
get_custom_dimension
Get a custom dimension with its channel groups and filters. Use key
Returns: Full custom dimension object with groups and filters.Example prompts:
channel for the Channel dimension. Returns groups in evaluation order — each has a name and a filter. Use this before update_custom_dimension to see current groups.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
key | string | Yes | The custom dimension key |
session_id | string | Yes | Session ID returned by analyze_request |
- “Show me the Channel dimension groups”
- “How is this custom dimension configured?”
create_custom_dimension
create_custom_dimension
Create a new custom dimension. Provide a name and optionally groups that define how values are categorized. Filters use the same dimensions as
Returns: Created custom dimension object.Example prompts:
run_report (ad_platform, campaign_name, utm_source, utm_medium, etc.). Use query_dimension_values to discover exact values before building group filter rules.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
name | string | Yes | Display name for the new dimension (e.g., Region, Product Category) |
groups | array | No | Groups defining how values are categorized. Each group has a name and filter. Groups are evaluated in order — first match wins |
session_id | string | Yes | Session ID returned by analyze_request |
- “Create a Region custom dimension with EMEA and North America groups”
- “Add a Brand vs Non-Brand dimension”
update_custom_dimension
update_custom_dimension
Update a custom dimension. Groups are evaluated in order — first match wins. Put specific rules first, broad rules last. Traffic not matching any group goes to
Returns: Updated custom dimension object.Example prompts:
Other automatically. Full replacement — groups not included are permanently removed. Call get_custom_dimension first to see current groups.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
key | string | Yes | Custom dimension key. Use channel for the Channel dimension |
name | string | No | New display name for the dimension |
groups | array | No | Channel definitions, evaluated in order. Each group has a name and filter (same format as run_report filters) |
session_id | string | Yes | Session ID returned by analyze_request |
- “Add a TikTok Ads channel to the Channel dimension”
- “Update the Channel dimension to include an Organic AI group”
- “Rename the Brand Search group”
reset_custom_dimensions_to_default
reset_custom_dimensions_to_default
Reset a project’s custom dimensions to the current default template (20-group Channel dimension). Requires SuperAdmin access.Parameters:
Returns: Confirmation that dimensions were reset.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “Reset the custom dimensions to the default template”
- “Apply the latest default Channel dimension to this project”
Audiences
Tools for inspecting audience definitions and memberships.list_audiences
list_audiences
List audiences for a project, optionally filtered by ML model or conversion. Returns id, name,
Returns: Array of audience objects.Example prompts:
isForever, filter, membershipDurationDays, and status for each audience.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
ml_model_id | string | No | Filter audiences by ML model |
conversion_id | string | No | Filter audiences by conversion |
session_id | string | Yes | Session ID returned by analyze_request |
- “What audiences are defined in this project?”
- “List all audiences associated with the Purchase conversion”
get_audience
get_audience
Get a single audience with full details including id, name,
Returns: Full audience configuration object.Example prompts:
projectId, isForever, filter, filterSql, membershipDurationDays, status, createdAt, and updatedAt.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
audience_id | string | Yes | The audience ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Query audience memberships for a specific client (anonymous ID) within a date range. Returns
Returns: Array of audience membership objects with entry and expiration times.Example prompts:
audienceId, audienceName, entryTime, and expirationTime for each membership.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
anonymous_id | string | Yes | The anonymous client ID to query audience memberships for |
from | string | Yes | Start date (ISO date, e.g., 2025-01-01) |
to | string | Yes | End date (ISO date, e.g., 2025-01-31) |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get audience inclusion statistics for a project: per-audience inclusion count and percent, total inclusion, total percent, and
Returns: Inclusion statistics with per-audience counts and percentages.Example prompts:
allUsers count. Optionally filter by ML model.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
ml_model_id | string | No | Filter inclusion stats by ML model |
session_id | string | Yes | Session ID returned by analyze_request |
- “What percentage of users are in each audience?”
- “Show me audience inclusion statistics”
Workflows
Tools for monitoring data processing workflows.list_workflows
list_workflows
List recent workflows for a SegmentStream project.Parameters:
Returns: Array of workflow objects.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
limit | number | No | Maximum number of workflows to return (default 20) |
session_id | string | Yes | Session ID returned by analyze_request |
- “Show me the recent workflows”
- “What data processing jobs ran today?”
get_workflow_status
get_workflow_status
Get the status and details of a specific workflow, including data source logs and errors.Parameters:
Returns: Workflow status object with data source logs and error details.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
workflow_id | string | Yes | The workflow ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get cost data quality metrics: quality scores (total, 7-day, 1-day) and histogram. Optionally filter by data source and date range.Parameters:
Returns: Quality scores and histogram data.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
data_source_id | number | No | Scope results to a specific data source |
date_from | string | No | Start date (YYYY-MM-DD) |
date_to | string | No | End date (YYYY-MM-DD) |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get identity graph statistics including user stitching distribution, key combinations, and data completeness.Parameters:
Returns: Identity graph statistics object.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
conversion_internal_id | string | No | Filter by internal conversion ID |
days_back | number | No | Number of days to look back |
use_users_v2 | boolean | No | Whether to use the users v2 engine |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
List incidents for a project with optional filtering by status and pagination.Parameters:
Returns: Array of incident objects.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
status | string | No | Filter by status: Ok or Error |
limit | number | No | Maximum number of incidents to return |
offset | number | No | Number of incidents to skip for pagination |
minimum_updated_at | string | No | Only return incidents updated after this ISO-8601 date |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
List all classifiers for a project with their configuration.Parameters:
Returns: Array of classifier objects.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What ML classifiers are configured?”
- “Show me the classifier settings for this project”
get_classifier
get_classifier
Get a single classifier with full configuration.Parameters:
Returns: Full classifier configuration object.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
classifier_id | string | Yes | The classifier ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “Show me the details of this classifier”
- “What model does this classifier use?”
list_classifier_models
list_classifier_models
List available classifier models with pricing information.Parameters:
Returns: Array of available classifier model types with pricing.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID returned by analyze_request |
- “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
List all portfolios for a project with their id, name, goal, granularity, hidden status, metrics (
Returns: Array of portfolio objects with configuration and summary metrics.Example prompts:
potentialMetric, actualMetric, actualSpend), targetsCount, isReady, and lastApplyTime.Parameters:| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What portfolios are configured in this project?”
- “List all optimization portfolios”
- “Which portfolios are ready for optimization?”
get_portfolio_history
get_portfolio_history
Get portfolio performance history. When called with only
Returns: Performance history with per-period metrics and optional per-campaign detail.Example prompts:
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:| Name | Type | Required | Description |
|---|---|---|---|
portfolio_id | string | Yes | The portfolio ID |
period | string | No | History period: LAST_MONTH, LAST_THREE_MONTHS (default), or LAST_SIX_MONTHS |
start_date | string | No | Period start date (ISO-8601, e.g., 2025-01-01). When provided with end_date, returns detailed per-campaign breakdowns |
end_date | string | No | Period end date (ISO-8601, e.g., 2025-01-31). When provided with start_date, returns detailed per-campaign breakdowns |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
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:
Returns: Optimization scenario with per-target results, marginal metrics, and diminishing return curves.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
portfolio_id | string | Yes | The portfolio ID |
total_budget_limit | number | No | Total budget constraint for the optimization period |
total_daily_budget_limit | number | No | Daily budget constraint for optimization |
optimization_version | string | No | Optimization algorithm version (default: v7) |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
List all experiments for a project with their status, preparation, and analysis results.Parameters:
Returns: Array of experiment objects with status and results.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | The project ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What experiments are running?”
- “Show me all geo tests and their status”
- “List completed experiments with their results”
get_experiment
get_experiment
Get a single experiment with full details including plots, preparation, and analysis results.Parameters:
Returns: Full experiment object with plots, preparation data, and analysis results.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
experiment_id | string | Yes | The experiment ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “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
Get available custom parameter keys for market-split experiments.Parameters:
Returns: Array of custom parameter keys.Example prompts:
| Name | Type | Required | Description |
|---|---|---|---|
conversion_id | string | Yes | The conversion ID |
session_id | string | Yes | Session ID returned by analyze_request |
- “What custom parameters can I use for geo test segmentation?”
- “List available custom parameter keys for experiments”