> ## 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.
# Supported tools
> Complete reference of all SegmentStream MCP tools — grouped by category with parameters, return values, and example prompts.
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:**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `user_prompt` | string | Yes | The user's question or request, verbatim |
| `user_intent` | string | No | What the user wants to achieve. Especially helpful when the message is short ("ok", "yes") |
| `project_id` | string | No | Omit to auto-resolve |
| `session_id` | string | No | Session 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:**
| 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` |
**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:**
| 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` |
**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:** None
**Returns:** 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | -------------- |
| `project_id` | string | Yes | The 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:**
| 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` |
**Returns:** Confirmation of the invitation.
**Example prompts:**
* "Invite [john@example.com](mailto:john@example.com) 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ---------------- | ------ | -------- | ---------------------------------------- |
| `data_source_id` | string | Yes | The data source ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:** None
**Returns:** 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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| --------------- | ------ | -------- | ---------------------------------------- |
| `conversion_id` | string | Yes | The conversion ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ----------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Human-readable model name |
| `algorithm` | string | Yes | `first_click` or `last_click` |
| `attribution_window` | number | No | Window in days (default `90`, `null` disables the cap) |
| `significant_touch_rule` | object | No | Boolean filter AST, only valid for `last_click`. `{ and: [...] } \| { or: [...] } \| { option, operator, value }`. Use `list_filter_options` for allowed `option` values |
| `self_reported_reattribution` | boolean | No | Whether the model applies self-reported reattribution (default `true`) |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ----------------------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `id` | string | Yes | The attribution model ID |
| `name` | string | No | Updated model name |
| `attribution_window` | number | No | Updated window in days; `null` disables the cap |
| `significant_touch_rule` | object | No | Updated boolean filter AST (last-click only). Same shape as `create_attribution_model` |
| `self_reported_reattribution` | boolean | No | Toggle self-reported reattribution |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| --------------------------------- | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `saved_report_id` | string | No | If provided, loads the saved report as the base; `settings` becomes a partial override |
| `settings` | object | Conditional | Full settings (when no `saved_report_id`) or override (when `saved_report_id`). See nested fields below |
| `settings.date_range` | object | Conditional | Primary 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_range` | object | No | Comparison date range for period-over-period analysis. Supports relative intervals (`preceding_period`, `same_period_last_year`) |
| `settings.dimensions` | array of string | No | Dimensions to group by (`campaign_name`, `ad_platform`, `channel`, `country`, etc.). `channel` is a built-in alias for the Channel grouped dimension |
| `settings.metrics` | array of string | No | Bare 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_conversions` | array | Conditional | `[{ id, conversion_id, attribution_id }]`. Required when conversion metrics are requested. Per-AC output columns are named `:` |
| `settings.filter` | object | No | Filter 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_by` | array | No | `[{ metric, direction, scope?, attributed_conversion_id? }]`. `scope` (`first_interval`/`second_interval`/`diff`) is only meaningful with a comparison date range |
| `limit` | number | No | Max rows (default 1000, max 1000) |
| `offset` | number | No | Row offset for pagination |
| `time_machine_date` | string | No | `YYYY-MM-DD` snapshot of tracked conversions and ML predictions as of that date. Must be a Sunday for projections |
| `format` | string | No | `json` (default) or `csv` |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| --------------------------------- | --------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `saved_report_id` | string | No | If provided, loads the saved report's chart config as the base |
| `settings` | object | Conditional | Same nested shape as `run_report` settings (no `comparison_date_range`) plus a nested `chart` sub-object |
| `settings.date_range` | object | Conditional | `{ interval, from, to }` |
| `settings.dimensions` | array of string | No | Dimensions to group by |
| `settings.attributed_conversions` | array | Conditional | Required when conversion metrics are plotted |
| `settings.filter` | object | No | Filter expression — same shape as `run_report` |
| `settings.chart.date_granularity` | string | No | `day` (default), `hour`, `week`, or `month` |
| `settings.chart.metrics` | array | No | Metrics to plot. Bare strings or `{ metric, attributed_conversion_id }` entries pinned to a specific AC |
| `time_machine_date` | string | No | `YYYY-MM-DD` snapshot date |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `report_id` | string | Yes | The saved report ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `id` | string | No | Existing report id to update. Omit to create. |
| `name` | string | Yes | Human-readable report name |
| `settings` | object | Yes | Full 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_id` | string | No | Session 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:**
| Name | Type | Required | Description |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `html_content` | string | Yes | The full HTML content of the artifact to share |
| `title` | string | Yes | Human-readable title for the artifact |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `tool` | string | Yes | Which 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `tool` | string | Yes | Which tool needs these values (determines the data source to query) |
| `field` | string | Yes | The field to query values for (e.g. `campaign_name`, `ad_platform`, `country`, `event.name`, `channel`, or a `custom_dimension_*` key) |
| `query` | string | No | Substring 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:**
| 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` |
**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 `user@example.com`?"
* "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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `key` | string | Yes | The grouped dimension key (e.g. `channel`) |
| `session_id` | string | Yes | Session 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:**
| 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 | Each 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_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `key` | string | Yes | Grouped dimension key. Use `channel` for the Channel dimension |
| `name` | string | No | New display name for the dimension |
| `groups` | array | No | Group 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_id` | string | Yes | Session 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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------- |
| `audience_id` | string | Yes | The audience ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------- |
| `workflow_id` | string | Yes | The workflow ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| --------------- | ------ | -------- | ---------------------------------------- |
| `classifier_id` | string | Yes | The classifier ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| 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` |
**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:**
| 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` |
**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:**
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| --------------- | ------ | -------- | ---------------------------------------- |
| `experiment_id` | string | Yes | The experiment ID |
| `session_id` | string | Yes | Session 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:**
| Name | Type | Required | Description |
| --------------- | ------ | -------- | ---------------------------------------- |
| `conversion_id` | string | Yes | The conversion ID |
| `session_id` | string | Yes | Session 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"