SegmentStream

https://docs.segmentstream.com/
Admin
SegmentStream lets you measure advertising ROI and other KPIs by consolidating first-party and...
Tokens:48,217
Snippets:721
Trust Score:9.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example: SDK Lead Conversion

Source: https://docs.segmentstream.com/project-configuration/sdk

Example of tracking a lead conversion using the SDK. No additional parameters are required.

```javascript
segmentstream.conversion({
  type: 'lead'
});
```

--------------------------------

### Looker Studio BigQuery Connection Example

Source: https://docs.segmentstream.com/attribution/bi-tools

This SQL query is used within Looker Studio to connect to your SegmentStream data in Google BigQuery. Ensure you replace 'YOUR_PROJECT' and 'YOUR_DATASET' with your actual project and dataset names. The query utilizes dynamic date parameters for start and end dates and a lookback period.

```sql
SELECT *
FROM `YOUR_PROJECT.YOUR_DATASET.bi_report_v4`(
  PARSE_DATE('%Y%m%d', @DS_START_DATE),
  PARSE_DATE('%Y%m%d', @DS_END_DATE),
  30
);
```

--------------------------------

### Example: SDK Purchase Conversion

Source: https://docs.segmentstream.com/project-configuration/sdk

Example of tracking a purchase conversion using the SDK with specific order details.

```javascript
segmentstream.conversion({
  type: 'purchase',
  id: 'ORD-12345',
  value: 199.99,
  currency: 'USD'
});
```

--------------------------------

### Example: SDK Subscription Conversion

Source: https://docs.segmentstream.com/project-configuration/sdk

Example of tracking a subscription conversion using the SDK, including a unique subscription ID.

```javascript
segmentstream.conversion({
  id: 'SUB-67890',
  type: 'subscription'
});
```

--------------------------------

### Hashed IP Address Example

Source: https://docs.segmentstream.com/project-configuration/no-ip-tracking

An example of the final anonymized IP address after applying salted hashing.

```text
f2c992f0a9f8d5c8b87e1a2b36a52e5bce9df51de60cdb3eaf5d66a6dfdfe281
```

--------------------------------

### GA4 Measurement Protocol Payload Example

Source: https://docs.segmentstream.com/project-configuration/lead-gen-business-integration/how-to-track-ad-platform-lead-forms-in-analytics-and-crm

An example payload for sending a 'lead_submission' event to GA4 via the Measurement Protocol. Includes client ID, page location, and custom parameters.

```json
{
  "client_id": "1d52c3ab-bb40-4b23-b7a2-9266a1c89d4b",
  "events": [{
    "name": "lead_submission",
    "params": {
      "page_location": "https://yourdomain.com/leadgen?utm_source=facebook&utm_medium=leadform&utm_campaign=summer_sale&utm_content=ad_1",
      "source_platform": "facebook",
      "form_type": "lead_form"
    }
  }]
}
```

--------------------------------

### URL with gclid parameter

Source: https://docs.segmentstream.com/attribution/faq

Example of a URL containing the gclid parameter, which is removed by iOS 17.

```url
https://site.com/?utm_source=google&utm_medium=cpc&utm_campaign=1467008&gclid=nvwieu5tryt5q9rut9wruqt33
```

--------------------------------

### URL after gclid parameter removal by iOS 17

Source: https://docs.segmentstream.com/attribution/faq

Example of a URL after the gclid parameter has been removed by iOS 17.

```url
https://site.com/?utm_source=google&utm_medium=cpc&utm_campaign=1467008
```

--------------------------------

### Example UTM Tagging for X Ads

Source: https://docs.segmentstream.com/project-configuration/data-sources/x-ads

Manually append UTM parameters to your website URL in X Ads to track campaign and ad group performance. This is necessary because X Ads do not support dynamic UTM parameters.

```plain text
https://segmentstream.com?utm_source=x&utm_medium=paid-social&utm_campaign=Offers&utm_id=36868108_47604328
```

--------------------------------

### list_experiment_custom_parameter_keys

Source: https://docs.segmentstream.com/mcp/supported-tools

Gets available custom parameter keys for market-split experiments. Requires conversion ID and session ID.

```APIDOC
## list_experiment_custom_parameter_keys

### Description
Get available custom parameter keys for market-split experiments.

### Parameters
#### Path Parameters
- `conversion_id` (string) - Required - The conversion ID
- `session_id` (string) - Required - Session ID returned by `analyze_request`

### Returns
Array of custom parameter keys.
```

--------------------------------

### Configure SDK Settings

Source: https://docs.segmentstream.com/project-configuration/sdk

Override default SegmentStream SDK settings by defining the `segmentstream_sdk_settings` object before the SDK script. This example shows how to set click ID propagation, cookieless pings, and local storage.

```html
<script>
  window.segmentstream_sdk_settings = {
    click_id_propagation: true,
    cookieless_pings: true,
    local_storage: false
  };
</script>
```

--------------------------------

### get_conversion

Source: https://docs.segmentstream.com/mcp/supported-tools

Get a single conversion with full configuration including type, counting behavior, matching conditions, custom SQL, audiences, and combined conversions.

```APIDOC
## get_conversion

### Description
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
#### Query Parameters
- **conversion_id** (string) - Required - The conversion ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Full conversion configuration object.
```

--------------------------------

### UTM Matching for YouTube & Partners Ads

Source: https://docs.segmentstream.com/project-configuration/data-sources/google-dv360

Configure default UTM parameters for YouTube & partners ads to ensure cost data is matched at the campaign level. This setup uses the campaign name for matching.

```plain text
utm_source=youtube&utm_medium=cpm&utm_campaign={campaign name in the DV360 interface}
```

--------------------------------

### list_conversions

Source: https://docs.segmentstream.com/mcp/supported-tools

List all conversions for a project. Returns id, name, type, counting behavior, and key configuration.

```APIDOC
## list_conversions

### Description
List all conversions for a project. Returns id, name, type (`online_purchase`, `online_event`, `sql`, `combined`, `probabilistic`), counting behavior, and key configuration.

### Parameters
#### Query Parameters
- **project_id** (string) - Required - The project ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Array of conversion objects.
```

--------------------------------

### get_classifier

Source: https://docs.segmentstream.com/mcp/supported-tools

Get a single classifier with full configuration.

```APIDOC
## get_classifier

### Description
Get a single classifier with full configuration.

### Parameters
#### Query Parameters
- **classifier_id** (string) - Required - The classifier ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Full classifier configuration object.
```

--------------------------------

### connect_data_source

Source: https://docs.segmentstream.com/mcp/supported-tools

Initiates the process of connecting a data source to a project. This is a multi-step process that may return an authentication URL, configuration fields, or confirm the connection.

```APIDOC
## connect_data_source

### Description
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.

### Method
APIDOC

### Endpoint
APIDOC

### Parameters
APIDOC

### Response
APIDOC
```

--------------------------------

### list_portfolios

Source: https://docs.segmentstream.com/mcp/supported-tools

Lists all portfolios for a project, including their ID, name, goal, granularity, hidden status, metrics, targets count, readiness status, and last apply time.

```APIDOC
## list_portfolios

### Description
Lists all portfolios for a project with their id, name, goal, granularity, hidden status, metrics (`potentialMetric`, `actualMetric`, `actualSpend`), `targetsCount`, `isReady`, and `lastApplyTime`.

### Parameters
#### Query Parameters
- **project_id** (string) - Required - The project ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Array of portfolio objects with configuration and summary metrics.
```

--------------------------------

### Direct SDK Conversion Tracking

Source: https://docs.segmentstream.com/project-configuration/sdk

Call this JavaScript method directly to trigger a conversion event. It supports 'purchase', 'lead', and 'signup' types, with optional 'id', 'value', and 'currency' parameters.

```javascript
segmentstream.conversion({
  type: 'purchase',    // Required: event type, such as 'purchase', 'lead', or 'signup'
  id: 'ORDER_ID',      // Optional: unique identifier for the conversion
  value: ORDER_VALUE,  // Optional: numeric value of the conversion
  currency: 'USD'      // Optional: currency code
});
```

--------------------------------

### Configure SegmentStream MCP Server in Codex

Source: https://docs.segmentstream.com/mcp/getting-started

Set up the SegmentStream MCP server in Codex by selecting 'Streamable HTTP' transport and providing the server name and URL. No bearer token or headers are needed.

```text
Name: SegmentStream
URL: https://mcp.segmentstream.com/mcp
```

--------------------------------

### get_portfolio_optimization

Source: https://docs.segmentstream.com/mcp/supported-tools

Fetches portfolio optimization data, including the current scenario, per-target optimization results with marginal metrics, diminishing return curves, and optional maturation/projection data.

```APIDOC
## get_portfolio_optimization

### Description
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
#### Query Parameters
- **portfolio_id** (string) - Required - The portfolio ID
- **total_budget_limit** (number) - Optional - Total budget constraint for the optimization period
- **total_daily_budget_limit** (number) - Optional - Daily budget constraint for optimization
- **optimization_version** (string) - Optional - Optimization algorithm version (default: `v7`)
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Optimization scenario with per-target results, marginal metrics, and diminishing return curves.
```

--------------------------------

### connect_data_source

Source: https://docs.segmentstream.com/mcp/supported-tools

Connects a data source to a SegmentStream project. This function guides users through the process of selecting a data source type and providing necessary configuration options.

```APIDOC
## connect_data_source

### Description
Connects a data source to a SegmentStream project. This function guides users through the process of selecting a data source type and providing necessary configuration options.

### Parameters
#### Path Parameters
- `project_id` (string) - Yes - The project ID
- `type` (string) - Yes - Data source type. Use display names: `Google Analytics 4`, `Google Ads`, `Meta Ads`, etc.
- `session_id` (string) - Yes - Session ID returned by `analyze_request`

#### Query Parameters
- `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`

### Returns
Next step in the connection flow (auth URL, configuration fields, or connection confirmation).
```

--------------------------------

### Get Anonymous User ID

Source: https://docs.segmentstream.com/project-configuration/lead-gen-business-integration/sending-website-lead-data-to-your-crm

Retrieve the SegmentStream anonymous ID. This ID is either the _ga cookie value for consented users or a generated ID for non-consented users.

```javascript
window.segmentstream.anonymousId()
```

--------------------------------

### get_portfolio_history

Source: https://docs.segmentstream.com/mcp/supported-tools

Retrieves the performance history of a portfolio. It can return a summary with per-period rows and plots, or detailed per-period data including per-campaign breakdowns when start and end dates are provided.

```APIDOC
## get_portfolio_history

### Description
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
#### Query Parameters
- **portfolio_id** (string) - Required - The portfolio ID
- **period** (string) - Optional - History period: `LAST_MONTH`, `LAST_THREE_MONTHS` (default), or `LAST_SIX_MONTHS`
- **start_date** (string) - Optional - Period start date (ISO-8601, e.g., `2025-01-01`). When provided with `end_date`, returns detailed per-campaign breakdowns
- **end_date** (string) - Optional - Period end date (ISO-8601, e.g., `2025-01-31`). When provided with `start_date`, returns detailed per-campaign breakdowns
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Performance history with per-period metrics and optional per-campaign detail.
```

--------------------------------

### list_available_data_sources

Source: https://docs.segmentstream.com/mcp/supported-tools

Lists all supported data source types, including their display name, authentication method, and category. This endpoint requires no parameters.

```APIDOC
## list_available_data_sources

### Description
List all supported data source types with their display name, auth method (`oauth2` or `api_key`), and category (`analytics`, `advertising`, `crm`).

### Method
APIDOC

### Endpoint
APIDOC

### Parameters
None

### Response
#### Success Response (200)
- Returns: Array of supported data source types with display name, auth method, and category.

### Response Example
APIDOC
```

--------------------------------

### Send Lead Data and Conversion Event

Source: https://docs.segmentstream.com/project-configuration/lead-gen-business-integration/sending-website-lead-data-to-your-crm

Example of sending lead data to a CRM using the SegmentStream anonymous ID and triggering a conversion event. Ensure both actions occur on the same page for accurate attribution.

```javascript
// code that sends data to the CRM
const clientId = window.segmentstream.anonymousId();
sendLeadToCRM({
    name: leadName,
    email: leadEmail,
    clientId: clientId
});

// code that sends data to SegmentStream
window.segmentstream.conversion({
    type: 'lead'
});
```

--------------------------------

### Add SegmentStream MCP Server via Claude CLI

Source: https://docs.segmentstream.com/mcp/getting-started

Use the Claude CLI to add the SegmentStream MCP server. You will be prompted to authenticate via your browser on first use.

```bash
claude mcp add segmentstream \
  --transport http \
  https://mcp.segmentstream.com/mcp
```

--------------------------------

### create_conversion

Source: https://docs.segmentstream.com/mcp/supported-tools

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`).

```APIDOC
## create_conversion

### Description
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
#### Request Body
- **project_id** (string) - Required - The SegmentStream project ID
- **name** (string) - Required - Conversion name (e.g., `Purchase`, `Lead`, `Sign up`)
- **type** (string) - Required - Conversion type: `online_purchase`, `online_event`, or `sql`
- **matching_conditions** (object) - Optional - Required for `online_event`. Conditions defining which events count as this conversion
- **custom_sql** (string) - Optional - Required for `sql` type. BigQuery SQL query defining the conversion
- **counting** (string) - Optional - `every_occurrence` (default) or `once_per_user`
- **counting_window** (number) - Optional - Days. Only used when counting is `once_per_user` (default 7)
- **value_type** (string) - Optional - `none` (default), `event_value`, or `fixed` (`online_event` only)
- **value** (number) - Optional - Fixed conversion value. Only when `value_type` is `fixed`
- **adjustment_window** (number) - Optional - Refund adjustment window in days (`online_purchase` only)
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Created conversion object.
```

--------------------------------

### Get Facebook fbp Cookie Value

Source: https://docs.segmentstream.com/project-configuration/conversions/conversions-export/facebook-conversions-export

Dynamically retrieves the value of the _fbp cookie. Use a function to ensure the cookie is available when accessed, as it might not be immediately present after the Facebook Pixel SDK loads.

```javascript
function getFbpCookie() {
  try {
    return /_fbp=(fb\.1\.\d+\.\d+)/.exec(window.document.cookie)[1];
  } catch (e) {
    return undefined;
  }
}
```

--------------------------------

### List SegmentStream Projects

Source: https://docs.segmentstream.com/mcp/getting-started

Use this command to verify your connection by listing your SegmentStream projects. The AI assistant calls the `list_active_projects` tool.

```text
List my SegmentStream projects
```

--------------------------------

### list_experiments

Source: https://docs.segmentstream.com/mcp/supported-tools

Lists all experiments for a project, including their status, preparation, and analysis results. Requires project ID and session ID.

```APIDOC
## list_experiments

### Description
List all experiments for a project with their status, preparation, and analysis results.

### Parameters
#### Path Parameters
- `project_id` (string) - Required - The project ID
- `session_id` (string) - Required - Session ID returned by `analyze_request`

### Returns
Array of experiment objects with status and results.
```

--------------------------------

### create_project

Source: https://docs.segmentstream.com/mcp/supported-tools

Creates a new SegmentStream project with External BigQuery integration. This process automatically resolves the billing account and creates a service account, returning the new project ID and service account email.

```APIDOC
## create_project

### Description
Create a new SegmentStream project with External BigQuery. Auto-resolves the billing account and creates a service account. Returns `projectId` and `serviceAccountEmail`.

### Parameters
#### Path Parameters
- **project_name** (string) - Required - Project name, typically the website domain (e.g., `example.com`)
- **timezone** (string) - Required - IANA timezone identifier (e.g., `Europe/London`, `America/New_York`)
- **currency** (string) - Required - ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`)
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Object with `projectId` and `serviceAccountEmail`.
```

--------------------------------

### Client-side User Context Fetching and Data Layer Push

Source: https://docs.segmentstream.com/project-configuration/no-ip-tracking

This snippet shows how a client-side script can fetch user context data from the server and push it to the dataLayer for analytics or other purposes.

```javascript
(async () => {
  const context = await fetch('/api/user-context').then(r => r.json());

  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'user_context',
    ip_hash: context.ip_hash,
    country: context.country,
    region: context.region,
    city: context.city,
  });
})();
```

--------------------------------

### Configure SegmentStream MCP Server in Cursor

Source: https://docs.segmentstream.com/mcp/getting-started

Add the SegmentStream MCP server configuration to your Cursor project's .cursor/mcp.json file. Authentication is handled via browser prompt on first use.

```json
{
  "mcpServers": {
    "segmentstream": {
      "type": "http",
      "url": "https://mcp.segmentstream.com/mcp"
    }
  }
}
```

--------------------------------

### Configure SegmentStream MCP Server in VS Code

Source: https://docs.segmentstream.com/mcp/getting-started

Create or edit the .vscode/mcp.json file in your project root to configure the SegmentStream MCP server. Browser authentication is required on first use.

```json
{
  "servers": {
    "segmentstream": {
      "type": "http",
      "url": "https://mcp.segmentstream.com/mcp"
    }
  }
}
```

--------------------------------

### run_report

Source: https://docs.segmentstream.com/mcp/supported-tools

Executes an aggregated report query, returning grouped metrics like conversions, ROAS, CPA, and cost, dimensioned by channel, campaign, or country. This is the primary tool for performance analytics. For individual conversion data, use `query_conversion_records`. Use `query_filter_option_values` to discover exact filter values. For a more token-efficient output, use `format: "csv"`.

```APIDOC
## run_report

### Description
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
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **project_id** (string) - Required - The project ID
- **saved_report_id** (string) - Optional - 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) - Optional - Comparison date range for period-over-period analysis. Supports relative intervals (`preceding_period`, `same_period_last_year`)
  - **settings.dimensions** (array of string) - Optional - Dimensions to group by (`campaign_name`, `ad_platform`, `channel`, `country`, etc.). `channel` is a built-in alias for the Channel grouped dimension

### Request Example
```json
{
  "project_id": "your_project_id",
  "settings": {
    "date_range": {
      "interval": "last_30_days"
    },
    "dimensions": ["campaign_name", "channel"]
  }
}
```

### Response
#### Success Response (200)
- **data** (array) - The report data, grouped by the specified dimensions.
- **total_metrics** (object) - Aggregated metrics for the entire report.

#### Response Example
```json
{
  "data": [
    {
      "campaign_name": "Summer Sale 2023",
      "channel": "Facebook",
      "conversions": 150,
      "cost": 1200.50,
      "roas": 3.5,
      "cpa": 8.00
    }
  ],
  "total_metrics": {
    "conversions": 5000,
    "cost": 40000.00,
    "roas": 4.0,
    "cpa": 8.00
  }
}
```
```

--------------------------------

### list_classifiers

Source: https://docs.segmentstream.com/mcp/supported-tools

List all classifiers for a project with their configuration.

```APIDOC
## list_classifiers

### Description
List all classifiers for a project with their configuration.

### Parameters
#### Query Parameters
- **project_id** (string) - Required - The project ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Returns
Array of classifier objects.
```

--------------------------------

### get_data_source_logs

Source: https://docs.segmentstream.com/mcp/supported-tools

Fetches import logs for a specific data source, including phase, timestamps, status, and error details. Requires project ID, data source ID, and session ID.

```APIDOC
## get_data_source_logs

### Description
Get import logs for a data source: phase, `startedAt`, `fillDate`, status, errors, and message.

### Method
APIDOC

### Endpoint
APIDOC

### Parameters
#### Query Parameters
- **project_id** (string) - Required - The project ID
- **data_source_id** (string) - Required - The data source ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Response
#### Success Response (200)
- Returns: Array of import log entries with phase, timestamps, status, and error details.

### Response Example
APIDOC
```

--------------------------------

### list_data_sources

Source: https://docs.segmentstream.com/mcp/supported-tools

Lists all data sources for a given SegmentStream project. It requires the project ID and a session ID.

```APIDOC
## list_data_sources

### Description
List all data sources for a SegmentStream project.

### Method
APIDOC

### Endpoint
APIDOC

### Parameters
#### Query Parameters
- **project_id** (string) - Required - The project ID
- **session_id** (string) - Required - Session ID returned by `analyze_request`

### Response
#### Success Response (200)
- Returns: Array of data source objects.

### Response Example
APIDOC
```
Tokens:
Raw