Supermetrics Marketing Analytics
Supermetrics Marketing Analytics · GPT 작업
Supermetrics MCP Server
Supermetrics MCP Server - An MCP (Model Context Protocol) server providing access to marketing data from connected platforms like Google Analytics, Facebook Ads, Google Ads, and more. This API enables LLMs to query marketing data, discover data sources and accounts, explore available fields, and retrieve performance metrics.
POST /mcp/accounts_discoveryList connected accountsDiscover connected accounts for a data source. Only call if data_source_discovery config shows has_account_list=true. RETURNS: account_id, account_name, group_name, ds_user, ds_user_display_name
POST /mcp/campaign_and_resource_getCampaign & Resource GetGet campaign details or list campaigns and related resources. resource_type determines what to query. Pass resource-type-specific options in the params object: - campaigns (default): list campaigns. params: {status}.
POST /mcp/campaign_createCreate CampaignCreate a campaign. Response: {results: [campaign], notes: [strings]}. Partial success: if campaign creates but ad group/ad fails, returns campaign_id + notes.
POST /mcp/campaign_updateUpdate CampaignUpdate an existing campaign. Only provided fields are changed. Response: {results: [campaign], notes: [strings]}. Notes explain ignored fields, platform limitations, and unchanged entities. Response ads include review status (APPROVED, APPROVED_LIMITED, DISAPPROVED, IN_REVIEW).
POST /mcp/contact_supermetricsContact SupermetricsSend product feedback, create a support ticket, or submit a sales enquiry with Supermetrics. When creating a support ticket, include any information that is relevant for solving it, eg. what was the user intention, which tools were used, what were the relevant trace IDs.
POST /mcp/data_queryRun a data queryRun a data query against a connected marketing platform.
POST /mcp/data_source_discoveryList available data sourcesDiscover available data sources or get a specific source's configuration. Without ds_id: lists all sources with IDs and auth status. With ds_id: returns full config — always call with ds_id after picking a source.
POST /mcp/field_discoveryList fields for a data sourceDiscover available fields (metrics and dimensions) for a data source. Only call if data_source_discovery config shows has_fields=true. If has_report_type_selection=true, each field belongs to one or more report types. All fields in a single data query must share a common report type.
POST /mcp/get_async_query_resultsGet query resultsRetrieve results from a data_query using its schedule_id. Call immediately after data_query returns. Keep polling until status is 'completed' or failed.
POST /mcp/get_todayGet today's dateGet current UTC date and time. Use before data_query with custom date ranges to resolve relative date references (e.g. "last month") into specific dates.
POST /mcp/user_infoGet my account infoRetrieve authenticated user information from Supermetrics.
GET /mcp/resources/docsMcp Server DocumentationSupermetrics MCP server documentation.
GET /mcp/resources/hubSupermetrics HubLink to the Supermetrics Hub for managing data sources, connections, and destinations.
원본 API 스키마
{
"openapi": "3.1.0",
"info": {
"title": "Supermetrics MCP Server",
"description": "Supermetrics MCP Server - An MCP (Model Context Protocol) server providing access to marketing data from connected platforms like Google Analytics, Facebook Ads, Google Ads, and more.\n\nThis API enables LLMs to query marketing data, discover data sources and accounts, explore available fields, and retrieve performance metrics.",
"version": "1.0.0",
"contact": {
"name": "Supermetrics",
"url": "https://supermetrics.com"
},
"license": {
"name": "Proprietary"
}
},
"servers": [
{
"url": "https://mcp.supermetrics.com",
"description": "Production server"
}
],
"security": [
{
"oauth2": []
}
],
"components": {
"schemas": {
"Error": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"description": "Error message"
}
},
"required": [
"success",
"error"
]
},
"SuccessResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"description": "Response data"
}
}
},
"AccountsdiscoveryResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"account_id": {
"type": "string"
},
"account_name": {
"type": "string"
}
}
}
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"CampaignandresourcegetResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"description": "Response data"
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"CampaigncreateResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"campaign_id": {
"type": "string",
"example": "123456789"
},
"name": {
"type": "string",
"example": "Spring Sale 2026"
},
"status": {
"type": "string",
"example": "ENABLED"
},
"platform": {
"type": "string",
"example": "google_ads"
},
"budget_amount": {
"type": "number",
"example": 100
},
"budget_type": {
"type": "string",
"example": "DAILY"
},
"start_date": {
"type": "string",
"format": "date"
},
"end_date": {
"type": "string",
"format": "date"
},
"platform_details": {
"type": "object",
"description": "Platform-specific details",
"properties": {
"campaign_type": {
"type": "string"
},
"bidding_strategy": {
"type": "string"
}
},
"additionalProperties": true
},
"ad_groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ad_group_id": {
"type": "string"
},
"name": {
"type": "string"
},
"ads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"CampaignupdateResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"campaign_id": {
"type": "string",
"example": "123456789"
},
"name": {
"type": "string",
"example": "Spring Sale 2026"
},
"status": {
"type": "string",
"example": "ENABLED"
},
"platform": {
"type": "string",
"example": "google_ads"
},
"budget_amount": {
"type": "number",
"example": 100
},
"budget_type": {
"type": "string",
"example": "DAILY"
},
"platform_details": {
"type": "object",
"description": "Platform-specific details",
"properties": {
"campaign_type": {
"type": "string"
},
"bidding_strategy": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"ContactsupermetricsResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"description": "Response data"
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"DataqueryResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"schedule_id": {
"type": "string"
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"DatasourcediscoveryResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"data_sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"type": "string"
}
}
}
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"FielddiscoveryResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"data_source": {
"type": "string"
},
"total": {
"type": "integer"
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"GetasyncqueryresultsResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"status": {
"type": "string"
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"GettodayResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"iso_string": {
"type": "string"
},
"timestamp": {
"type": "integer"
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
},
"UserinfoResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "object",
"properties": {
"license": {
"type": "object",
"properties": {
"license_id": {
"type": "integer",
"example": 48390
},
"team_id": {
"type": "integer",
"example": 51
},
"license_model": {
"type": "string",
"example": "FULL"
},
"start_date": {
"type": "string",
"format": "date",
"example": "2018-11-14"
},
"end_date": {
"type": "string",
"format": "date",
"example": "2035-11-28"
},
"license_status": {
"type": "string",
"example": "VALID"
},
"license_days_left": {
"type": "integer",
"example": 3598
},
"license_url": {
"type": "string",
"format": "uri",
"example": "https://hub.ismtip.com/subscriptions/48390"
}
},
"required": [
"license_id",
"team_id",
"license_model",
"start_date",
"end_date",
"license_status",
"license_days_left",
"license_url"
]
},
"product": {
"type": "object",
"properties": {
"product_code": {
"type": "string",
"example": "API"
},
"product_full_title": {
"type": "string",
"example": "Supermetrics API"
},
"product_logo_url": {
"type": "string",
"format": "uri",
"example": "https://assets.supermetrics.com/images/productLogo/icon-api.svg"
}
},
"required": [
"product_code",
"product_full_title",
"product_logo_url"
]
},
"user": {
"type": "object",
"properties": {
"sub": {
"type": "string",
"example": "86f0d65c38ef07c74aa9ccbab097f6ca58976552"
},
"name": {
"type": "string",
"example": "John Doe"
},
"given_name": {
"type": "string",
"example": "John"
},
"family_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"format": "email",
"example": "john.doe@example.com"
},
"user_info": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "user"
},
"user_id": {
"type": "string",
"example": "usr_13"
},
"email": {
"type": "string",
"format": "email",
"example": "john.doe@example.com"
}
},
"required": [
"type",
"user_id",
"email"
]
},
"team_info": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "team"
},
"team_id": {
"type": "string",
"example": "tm_51"
},
"name": {
"type": "string",
"example": "Marketing Team"
},
"display_id": {
"type": "string",
"example": "4444444"
},
"company_name": {
"type": "string",
"example": "Acme Corp"
},
"company_country": {
"type": "string",
"example": "US"
}
},
"required": [
"type",
"team_id",
"name",
"display_id",
"company_name",
"company_country"
]
},
"team_permissions": {
"type": "object",
"properties": {
"user_role": {
"type": "string",
"example": "OWNER"
}
},
"required": [
"user_role"
]
}
},
"required": [
"sub",
"name",
"given_name",
"family_name",
"email",
"user_info",
"team_info",
"team_permissions"
]
}
},
"required": [
"license",
"product",
"user"
]
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actionable guidance for the user, e.g. licensing or usage instructions."
}
},
"required": [
"success",
"data"
]
}
},
"securitySchemes": {
"oauth2": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://api.supermetrics.com/oauth/authorize",
"tokenUrl": "https://api.supermetrics.com/oauth/token",
"refreshUrl": "https://api.supermetrics.com/oauth/token",
"scopes": {}
}
},
"description": "OAuth 2.0 authorization with DCR (Dynamic Client Registration) support"
}
}
},
"paths": {
"/mcp/accounts_discovery": {
"post": {
"summary": "List connected accounts",
"description": "Discover connected accounts for a data source. Only call if data_source_discovery config shows has_account_list=true. RETURNS: account_id, account_name, group_name, ds_user, ds_user_display_name",
"operationId": "accountsdiscovery",
"tags": [
"Discovery"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ds_id": {
"type": "string",
"description": "Data source ID that can be retrieved using the data_source_discovery tool. Examples: 'FA' for Facebook Ads, 'AW' for Google Ads, 'GAWA' for Google Analytics.",
"title": "Data Source ID"
},
"compress": {
"type": "boolean",
"description": "Enable TOON compression. Returns data as a compact text string instead of JSON.",
"title": "Compress response"
},
"filter": {
"type": "string",
"description": "Optional filter string. Case-insensitive filtering against all account fields including account ID, name and group. Supports multiple comma-separated values to match any of them (e.g. 'act_123,act_456').",
"title": "Filter accounts"
}
},
"required": [
"ds_id"
],
"example": {
"ds_id": "GAWA"
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountsdiscoveryResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/campaign_and_resource_get": {
"post": {
"summary": "Campaign & Resource Get",
"description": "Get campaign details or list campaigns and related resources. resource_type determines what to query. Pass resource-type-specific options in the params object: - campaigns (default): list campaigns. params: {status}.",
"operationId": "campaignandresourceget",
"tags": [
"Campaign Management"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ds_id": {
"type": "string",
"description": "Data source code for the ad platform. 'AW' for Google Ads, 'FA' for Meta Ads, 'AC' for Microsoft Ads, 'TIK' for TikTok Ads, 'LIA' for LinkedIn Ads."
},
"account_id": {
"type": "string",
"description": "Platform ad account ID from accounts_discovery. Do NOT use account names. Google Ads: e.g. '1234567890'. Meta Ads: e.g. 'act_123456'. If unsure, call accounts_discovery with the ds_id first to find valid account IDs."
},
"max_rows": {
"type": "integer",
"description": "Max results to return. Applies to all resource types."
},
"resource_type": {
"type": "string",
"description": "What to query: campaigns (default), health_check, assets, pages, posts (FA only), keyword_ideas, keyword_volumes, targeting_search, reach_estimate, audiences, recommendations, history, or conversions."
},
"params": {
"type": "string",
"description": "Resource-type-specific parameters. See ResourceParams for which fields apply to each resource_type."
}
},
"required": [
"ds_id",
"account_id"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CampaignandresourcegetResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/campaign_create": {
"post": {
"summary": "Create Campaign",
"description": "Create a campaign. Response: {results: [campaign], notes: [strings]}. Partial success: if campaign creates but ad group/ad fails, returns campaign_id + notes.",
"operationId": "campaigncreate",
"tags": [
"Campaign Management"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ds_id": {
"type": "string",
"description": "Data source code for the ad platform. 'AW' for Google Ads, 'FA' for Meta Ads, 'AC' for Microsoft Ads, 'TIK' for TikTok Ads, 'LIA' for LinkedIn Ads."
},
"account_id": {
"type": "string",
"description": "Platform ad account ID from accounts_discovery. Do NOT use account names. Google Ads: e.g. '1234567890'. Meta Ads: e.g. 'act_123456'. If unsure, call accounts_discovery with the ds_id first to find valid account IDs."
},
"name": {
"type": "string",
"description": "Campaign name"
},
"status": {
"type": "string",
"description": "Always created as PAUSED. Use campaign_update to enable after review."
},
"budget_amount": {
"type": "number",
"description": "Budget amount in account currency"
},
"budget_type": {
"type": "string",
"description": "Budget type: DAILY or LIFETIME. LIA: only LIFETIME at campaign level. AC: LIFETIME only works on AUDIENCE campaigns."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format. AC: silently ignored by the Microsoft API."
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (required for LIFETIME budgets). AC: silently ignored by the Microsoft API."
},
"targeting": {
"type": "string",
"description": "Campaign-level targeting defaults inherited by all ad groups"
},
"extensions": {
"type": "string",
"description": "Ad extensions (AW/AC — sitelinks, callouts, snippets; AW also supports image extensions). Ignored on FA/TIK."
},
"platform_settings": {
"type": "object",
"additionalProperties": true,
"description": "Platform-specific settings. AW: {campaign_type (SEARCH, DISPLAY, PERFORMANCE_MAX, SHOPPING, VIDEO, DEMAND_GEN), bidding_strategy, bidding_config (see below), network_settings}. bidding_config (AW/AC/FA): {target_roas (float multiplier, e.g. 3.5 = 350% ROAS — used with TARGET_ROAS), target_cpa (float in account currency, e.g. 5.0 = $5 — used with TARGET_CPA)}. Works the same on all platforms. AC: {campaign_type (SEARCH, AUDIENCE, SHOPPING, DYNAMIC_SEARCH, PERFORMANCE_MAX), bidding_strategy (MAX_CLICKS, MAX_CONVERSIONS, MANUAL_CPC, TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE, ENHANCED_CPC)}. FA: {objective (OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION), special_ad_categories, buying_type, campaign_budget_optimization (true=CBO on, budget at campaign level; false=CBO off, budget per ad set)}. TIK: {objective_type (TRAFFIC, LEAD_GENERATION, REACH, VIDEO_VIEWS, CONVERSIONS, APP_INSTALL), promotion_type (WEBSITE, APP, SHOP — defaults to WEBSITE), placement_type (PLACEMENT_TYPE_AUTOMATIC default)}.LIA: campaign-level platform_settings are optional. Ad group platform_settings are where LIA-specific options go (campaign_type, cost_type, objective_type, daily_budget)."
},
"bidding_strategy": {
"type": "string",
"description": "Bidding strategy. Also accepted inside platform_settings. AW: MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS. For TARGET_ROAS, set the target value via platform_settings.bidding_config.target_roas (float multiplier, e.g. 3.5 = 350% ROAS). Without it, optimizes for max value with no target. For TARGET_CPA, set target via platform_settings.bidding_config.target_cpa (float in account currency, e.g. 5.0 = $5). AC: MAX_CLICKS, MAX_CONVERSIONS, MANUAL_CPC, ENHANCED_CPC, TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE. FA: LOWEST_COST_WITHOUT_CAP (default), LOWEST_COST_WITH_BID_CAP, COST_CAP. FA also accepts TARGET_ROAS — use bidding_config.target_roas to set the target. Auto-sets OUTCOME_SALES objective, VALUE optimization, and pixel if not specified."
},
"ad_groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ad groups (AW/AC) or ad sets (FA/TIK) to create with the campaign."
},
"url_tags": {
"type": "string",
"description": "Campaign-level URL tracking parameters appended to ad links"
}
},
"required": [
"ds_id",
"account_id",
"name"
],
"example": {
"ds_id": "AW",
"account_id": "1234567890",
"name": "Spring Sale 2026",
"status": "PAUSED",
"budget_amount": 100,
"budget_type": "DAILY",
"platform_settings": {
"campaign_type": "SEARCH",
"bidding_strategy": "MAXIMIZE_CONVERSIONS"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CampaigncreateResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/campaign_update": {
"post": {
"summary": "Update Campaign",
"description": "Update an existing campaign. Only provided fields are changed. Response: {results: [campaign], notes: [strings]}. Notes explain ignored fields, platform limitations, and unchanged entities. Response ads include review status (APPROVED, APPROVED_LIMITED, DISAPPROVED, IN_REVIEW).",
"operationId": "campaignupdate",
"tags": [
"Campaign Management"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ds_id": {
"type": "string",
"description": "Data source code for the ad platform. 'AW' for Google Ads, 'FA' for Meta Ads, 'AC' for Microsoft Ads, 'TIK' for TikTok Ads, 'LIA' for LinkedIn Ads."
},
"account_id": {
"type": "string",
"description": "Platform ad account ID from accounts_discovery. Do NOT use account names. Google Ads: e.g. '1234567890'. Meta Ads: e.g. 'act_123456'. If unsure, call accounts_discovery with the ds_id first to find valid account IDs."
},
"campaign_id": {
"type": "string",
"description": "Platform campaign ID to update. Get campaign IDs by calling campaign_and_resource_get with resource_type='campaigns'."
},
"status": {
"type": "string",
"description": "Campaign status: ENABLED, PAUSED, or REMOVED"
},
"name": {
"type": "string",
"description": "New campaign name"
},
"budget_amount": {
"type": "number",
"description": "New budget amount in account currency"
},
"budget_type": {
"type": "string",
"description": "New budget type: DAILY or LIFETIME. LIA: only LIFETIME at campaign level. AC: LIFETIME only works on AUDIENCE campaigns."
},
"start_date": {
"type": "string",
"description": "New start date in YYYY-MM-DD format. AC: silently ignored by the Microsoft API."
},
"end_date": {
"type": "string",
"description": "New end date in YYYY-MM-DD format. AC: silently ignored by the Microsoft API."
},
"targeting": {
"type": "string",
"description": "Replace campaign targeting (removes old, adds new)"
},
"extensions": {
"type": "string",
"description": "Replace extensions (removes old, adds new) — AW/AC. Ignored on FA/TIK."
},
"platform_settings": {
"type": "object",
"additionalProperties": true,
"description": "Platform-specific settings to update. AW/AC/FA: {bidding_config: {target_roas (float, e.g. 3.5 = 350%), target_cpa (float, e.g. 5.0 = $5)}}. AW: {ad_schedule, bid_adjustments}. FA: {campaign_budget_optimization (true=CBO on, false=CBO off)}."
},
"bidding_strategy": {
"type": "string",
"description": "New bidding strategy. AW: MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS. For TARGET_ROAS, set the target value via platform_settings.bidding_config.target_roas (float multiplier, e.g. 3.5 = 350% ROAS). Without it, optimizes for max value with no target. For TARGET_CPA, set target via platform_settings.bidding_config.target_cpa (float in account currency, e.g. 5.0 = $5). AC: MAX_CLICKS, MAX_CONVERSIONS, MANUAL_CPC, ENHANCED_CPC, TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE. FA: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP. FA also accepts TARGET_ROAS — use bidding_config.target_roas to set the target. IMPORTANT: FA bid strategy changes require the campaign to have a budget. CBO-off campaigns (budget at ad set level) cannot have their bid strategy changed. LOWEST_COST_WITH_BID_CAP requires bid_amount on each ad set."
},
"ad_groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ad groups to create (no id) or update (with id). Only provided fields change on update."
},
"url_tags": {
"type": "string",
"description": "Campaign-level URL tracking parameters appended to ad links"
},
"remove_ad_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ad IDs to remove"
},
"remove_ad_group_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ad group / ad set IDs to remove"
}
},
"required": [
"ds_id",
"account_id",
"campaign_id"
],
"example": {
"ds_id": "AW",
"account_id": "1234567890",
"campaign_id": "123456789",
"name": "Updated Campaign Name",
"budget_amount": 200
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CampaignupdateResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/contact_supermetrics": {
"post": {
"summary": "Contact Supermetrics",
"description": "Send product feedback, create a support ticket, or submit a sales enquiry with Supermetrics. When creating a support ticket, include any information that is relevant for solving it, eg. what was the user intention, which tools were used, what were the relevant trace IDs.",
"operationId": "contactsupermetrics",
"tags": [
"Tools"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of contact: 'feedback' for product feedback/feature requests, 'support' for technical issues, 'sales' for sales enquiries and demo requests"
},
"subject": {
"type": "string",
"description": "Brief summary of the feedback or issue"
},
"message": {
"type": "string",
"description": "Detailed description. Include relevant context: tools used, errors encountered, data sources involved, trace IDs"
},
"category": {
"type": "string",
"description": "Support ticket category. Only used when type is 'support'"
},
"ds_id": {
"type": "string",
"description": "Supermetrics data source ID, e.g. 'GAWA', 'FA', 'AW'. Use when feedback or problem is related to a specific data source"
},
"firstname": {
"type": "string",
"description": "Contact's first name. Required when type is 'sales'"
},
"lastname": {
"type": "string",
"description": "Contact's last name. Required when type is 'sales'"
},
"company": {
"type": "string",
"description": "Contact's company name. Required when type is 'sales'"
},
"country": {
"type": "string",
"description": "Contact's country. Required when type is 'sales'"
},
"industry": {
"type": "string",
"description": "Contact's industry. Used when type is 'sales'"
}
},
"required": [
"type",
"subject",
"message"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactsupermetricsResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/data_query": {
"post": {
"summary": "Run a data query",
"description": "Run a data query against a connected marketing platform.",
"operationId": "dataquery",
"tags": [
"Data Query"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ds_id": {
"type": "string",
"description": "Data source ID that can be retrieved using the data_source_discovery tool. Examples: 'FA' for Facebook Ads, 'AW' for Google Ads, 'GAWA' for Google Analytics.",
"title": "Data Source ID"
},
"ds_accounts": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Account IDs or free-text identifiers, as a comma-separated string or list. Example: '12345,67890' for multiple account IDs. Required when has_account_list=true (use IDs from accounts_discovery) or when is_free_text_account_required=true on the selected report type (e.g. a page alias, URL, or profile name). Omit only when neither condition applies.",
"title": "Data Source Accounts"
},
"fields": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Metrics and dimensions to query as a comma-separated string e.g. 'impressions,clicks,cost'.\n\nUse field_discovery to list available field IDs. Only the IDs returned by field_discovery can be used. You may mix metrics (numerical) and dimensions (categorical) fields.\n\nRequired for data sources where has_fields=true (check data_source_discovery config mode). Omit for data sources that don't use fields.\n\nCompatibility rule: All selected fields must share at least one common 'report_type' value. If the fields' metadata includes a 'report_types' list, only include fields that have at least one overlapping report_type; otherwise, the query will be invalid.\n\nWhen querying monetary metrics, include a currency dimension field if available from field_discovery.",
"title": "Data Source Fields"
},
"date_range_type": {
"type": "string",
"description": "Choose one of two approaches:\n1. Use 'custom' and provide start_date and end_date.\n2. Use a relative range in the format 'last_X_Y' (e.g., 'last_7_days', 'last_3_months').\n - Append '_inc' to include the current period (e.g., 'last_7_days_inc').",
"title": "Date Range Type"
},
"start_date": {
"type": "string",
"description": "Required if date_range_type='custom'. Date in YYYY-MM-DD format (e.g., '2024-01-01').",
"title": "Start Date"
},
"end_date": {
"type": "string",
"description": "Required if date_range_type='custom'. Date in YYYY-MM-DD format (e.g., '2024-01-31').",
"title": "End Date"
},
"timezone": {
"type": "string",
"description": "Optionally set the timezone for date calculations (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). Uses IANA timezone names. If not specified, uses UTC.",
"title": "Timezone"
},
"filters": {
"type": "string",
"description": "Filter expression string. Each condition has the form:\n[field_name] [operator] [value]\nConditions can be combined with AND / OR.\n\nSupported operators:\n- '==' → equals\n- '!=' → does not equal\n- '>' → greater than\n- '>=' → greater than or equal to\n- '<' → less than\n- '<=' → less than or equal to\n- '=@' → contains (case-insensitive, dimensions only)\n- '!@' → does not contain (case-insensitive, dimensions only)\n- '=~' → matches regular expression (dimensions only)\n- '!~' → does not match regular expression (dimensions only)\n\n- '[]' → in list (include comma-separated list of values)\n\nExamples:\n- \"country == United States\"\n- \"country == United States OR country == Canada\"\n- \"sessions > 1000 AND deviceCategory == mobile\"\n- \"campaign_name =@ spring_sale\"\n- \"pagePath =~ ^/products/.*\"\n- \"country [] United States,Canada\"",
"title": "Filters"
},
"settings": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string"
}
],
"description": "All data source-specific settings from data_source_discovery config mode. Pass as a JSON object. IMPORTANT: Every setting_id from data_source_discovery (report_type, common_settings, report-type-specific settings) MUST be passed inside this object — do NOT pass them as separate root-level parameters. Example: {\"report_type\": \"TopIosApps\", \"country\": \"US\", \"list_type\": \"top-free\"}",
"title": "Settings"
},
"compare_type": {
"type": "string",
"description": "Select how to compare results to an earlier period:\n- 'prev_range': previous period of the same length\n- 'prev_year': same period in the previous year\n- 'prev_year_weekday': same weekdays in the previous year\n- 'custom': user-defined period (requires compare_start_date and compare_end_date)",
"title": "Comparison Period Type"
},
"compare_show": {
"type": "string",
"description": "How to display the comparison:\n- 'perc_change': percentage change (default)\n- 'abs_change': absolute change\n- 'value': raw value from the comparison period",
"title": "Comparison Value Type"
},
"compare_start_date": {
"type": "string",
"description": "Required if compare_type='custom'.\nStart date of the custom comparison period, in YYYY-MM-DD format (e.g., '2024-01-01').",
"title": "Comparison Period Start Date"
},
"compare_end_date": {
"type": "string",
"description": "Required if compare_type='custom'.\nEnd date of the custom comparison period, in YYYY-MM-DD format (e.g., '2024-01-31').",
"title": "Comparison Period End Date"
},
"max_rows": {
"type": "integer",
"description": "Maximum number of rows to return. Defaults to 1000 if not specified. Increase for larger datasets (e.g. 5000 or 10000). Keep under 10,000 for best performance.",
"title": "Maximum Rows"
}
},
"required": [
"ds_id"
],
"example": {
"ds_id": "GAWA",
"ds_accounts": [
"123456789"
],
"fields": [
"date",
"sessions",
"pageviews"
],
"date_range_type": "last_7_days"
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataqueryResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/data_source_discovery": {
"post": {
"summary": "List available data sources",
"description": "Discover available data sources or get a specific source's configuration. Without ds_id: lists all sources with IDs and auth status. With ds_id: returns full config — always call with ds_id after picking a source.",
"operationId": "datasourcediscovery",
"tags": [
"Discovery"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"compress": {
"type": "boolean",
"description": "Enable TOON compression. Returns data as a compact text string instead of JSON.",
"title": "Compress response"
},
"ds_id": {
"type": "string",
"description": "Optional. When provided, returns the full configuration for this data source including capabilities (has_account_list, has_fields), report types, and settings. When omitted, returns the list of all available data sources.",
"title": "Data Source ID"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasourcediscoveryResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/field_discovery": {
"post": {
"summary": "List fields for a data source",
"description": "Discover available fields (metrics and dimensions) for a data source. Only call if data_source_discovery config shows has_fields=true. If has_report_type_selection=true, each field belongs to one or more report types. All fields in a single data query must share a common report type.",
"operationId": "fielddiscovery",
"tags": [
"Discovery"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ds_id": {
"type": "string",
"description": "Data source ID that can be retrieved using the data_source_discovery tool. Examples: 'FA' for Facebook Ads, 'AW' for Google Ads, 'GAWA' for Google Analytics.",
"title": "Data Source ID"
},
"compress": {
"type": "boolean",
"description": "Enable TOON compression. Returns data as a compact text string instead of JSON.",
"title": "Compress response"
},
"filter": {
"type": "string",
"description": "Optional filter string. Case-insensitive filtering against field ID, name, description, type and group. Supports multiple comma-separated values to match any of them (e.g. 'click,impression').",
"title": "Filter fields"
}
},
"required": [
"ds_id"
],
"example": {
"ds_id": "GAWA",
"filter": "click"
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FielddiscoveryResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/get_async_query_results": {
"post": {
"summary": "Get query results",
"description": "Retrieve results from a data_query using its schedule_id. Call immediately after data_query returns. Keep polling until status is 'completed' or failed.",
"operationId": "getasyncqueryresults",
"tags": [
"Data Query"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schedule_id": {
"type": "string",
"description": "The schedule ID returned from a data_query request. Schedule ID must be exactly the same as returned in the data_query response. Treat IDs as opaque. Copy verbatim. Do not abbreviate, format, or paraphrase.",
"title": "Schedule ID"
},
"compress": {
"type": "boolean",
"description": "Enable TOON compression. Returns data as a compact text string instead of JSON.",
"title": "Compress response"
}
},
"required": [
"schedule_id"
],
"example": {
"schedule_id": "abc123-def456-ghi789"
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetasyncqueryresultsResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/get_today": {
"post": {
"summary": "Get today's date",
"description": "Get current UTC date and time. Use before data_query with custom date ranges to resolve relative date references (e.g. \"last month\") into specific dates.",
"operationId": "gettoday",
"tags": [
"Utilities"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GettodayResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/user_info": {
"post": {
"summary": "Get my account info",
"description": "Retrieve authenticated user information from Supermetrics.",
"operationId": "userinfo",
"tags": [
"Authentication"
],
"x-openai-isConsequential": false,
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserinfoResponse"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/resources/docs": {
"get": {
"summary": "Mcp Server Documentation",
"description": "Supermetrics MCP server documentation.",
"operationId": "mcpserverdocumentation",
"tags": [
"Resources"
],
"x-openai-isConsequential": false,
"responses": {
"200": {
"description": "Resource content",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/mcp/resources/hub": {
"get": {
"summary": "Supermetrics Hub",
"description": "Link to the Supermetrics Hub for managing data sources, connections, and destinations.",
"operationId": "supermetricshub",
"tags": [
"Resources"
],
"x-openai-isConsequential": false,
"responses": {
"200": {
"description": "Resource content",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"tags": [
{
"name": "Data Query",
"description": "Core data querying operations"
},
{
"name": "Discovery",
"description": "Data source, account, and field discovery"
},
{
"name": "Authentication",
"description": "User authentication and profile information"
},
{
"name": "Utilities",
"description": "Utility functions and helpers"
},
{
"name": "Resources",
"description": "Server resources and documentation"
},
{
"name": "Campaign Management",
"description": "Create, update, and manage ad campaigns"
}
]
}