Meta Ads MCP: read ad accounts and signal health; propose governed changes under Ask or Full.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Store a performance rule disabled. Enabling requires an explicit update; this never evaluates or proposes actions.
Both arrivals and cost conditions must hold over the last 3 complete days in the account timezone. Supply the complete definition when editing.
Maximum latest revisions; current_revision is always returned separately.
Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write.
Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.
Store a performance rule disabled. Enabling requires an explicit update; this never evaluates or proposes actions.
| Argument | Type | Description |
|---|---|---|
| name* | string | |
| limit | integer | Maximum latest revisions; current_revision is always returned separately. |
| cursor | string | Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write. |
| definition* | object | Both arrivals and cost conditions must hold over the last 3 complete days in the account timezone. Supply the complete definition when editing. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| platform_ad_account_id* | integer |
{
"type": "object",
"required": [
"name",
"definition",
"platform_ad_account_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 25,
"minimum": 1,
"description": "Maximum latest revisions; current_revision is always returned separately."
},
"cursor": {
"type": "string",
"description": "Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write."
},
"definition": {
"type": "object",
"required": [
"target_level",
"action",
"minimum_counted_arrivals",
"cost_comparison",
"cost_ratio"
],
"properties": {
"action": {
"enum": [
"pause",
"increase_budget",
"decrease_budget"
],
"type": "string"
},
"cost_ratio": {
"type": "number",
"maximum": 10,
"minimum": 0.1,
"description": "Target cost per counted arrival divided by whole-account cost per counted arrival."
},
"target_level": {
"enum": [
"ad",
"ad_set",
"campaign"
],
"type": "string"
},
"cost_comparison": {
"enum": [
"at_least",
"at_most"
],
"type": "string"
},
"budget_change_percent": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Required for daily-budget changes on ad sets or campaigns; omit for pause. Pause targets only ads or ad sets."
},
"minimum_counted_arrivals": {
"type": "integer",
"minimum": 50,
"description": "Counted arrivals on the target. At least 100 for a budget increase."
}
},
"description": "Both arrivals and cost conditions must hold over the last 3 complete days in the account timezone. Supply the complete definition when editing.",
"additionalProperties": false
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"platform_ad_account_id": {
"type": "integer",
"minimum": 1
}
}
}List stored performance rules available to this workspace key. This does not evaluate them.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| cursor | string | Continue using rules.next_cursor; use actions.rules.show for detail. |
| per_page | integer | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 10000000000000000,
"minimum": 1
},
"cursor": {
"type": "string",
"description": "Continue using rules.next_cursor; use actions.rules.show for detail."
},
"per_page": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Read a stored performance rule and its immutable revisions, with author type only.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum latest revisions; current_revision is always returned separately. |
| cursor | string | Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write. |
| run_id | string | Read decisions for one run belonging to this rule. |
| rule_id* | string | The action rule ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| decisions_cursor | string | Continue decisions using runs[].next_cursor; requires run_id. |
{
"type": "object",
"required": [
"rule_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 5,
"maximum": 25,
"minimum": 1,
"description": "Maximum latest revisions; current_revision is always returned separately."
},
"cursor": {
"type": "string",
"description": "Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write."
},
"run_id": {
"type": "string",
"description": "Read decisions for one run belonging to this rule."
},
"rule_id": {
"type": "string",
"pattern": "^[0-7][0-9a-hjkmnp-tv-z]{25}$",
"description": "The action rule ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"decisions_cursor": {
"type": "string",
"description": "Continue decisions using runs[].next_cursor; requires run_id."
}
}
}Edit a stored performance rule by appending a revision, or explicitly enable or disable it. This never evaluates or proposes actions.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| limit | integer | Maximum latest revisions; current_revision is always returned separately. |
| cursor | string | Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write. |
| enabled | boolean | Explicitly enable or disable the stored rule. |
| rule_id* | string | The action rule ID. |
| definition | object | Both arrivals and cost conditions must hold over the last 3 complete days in the account timezone. Supply the complete definition when editing. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"rule_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 25,
"minimum": 1,
"description": "Maximum latest revisions; current_revision is always returned separately."
},
"cursor": {
"type": "string",
"description": "Read older revisions using rule.next_cursor. Continue through actions.rules.show to avoid another write."
},
"enabled": {
"type": "boolean",
"description": "Explicitly enable or disable the stored rule."
},
"rule_id": {
"type": "string",
"pattern": "^[0-7][0-9a-hjkmnp-tv-z]{25}$",
"description": "The action rule ID."
},
"definition": {
"type": "object",
"required": [
"target_level",
"action",
"minimum_counted_arrivals",
"cost_comparison",
"cost_ratio"
],
"properties": {
"action": {
"enum": [
"pause",
"increase_budget",
"decrease_budget"
],
"type": "string"
},
"cost_ratio": {
"type": "number",
"maximum": 10,
"minimum": 0.1,
"description": "Target cost per counted arrival divided by whole-account cost per counted arrival."
},
"target_level": {
"enum": [
"ad",
"ad_set",
"campaign"
],
"type": "string"
},
"cost_comparison": {
"enum": [
"at_least",
"at_most"
],
"type": "string"
},
"budget_change_percent": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Required for daily-budget changes on ad sets or campaigns; omit for pause. Pause targets only ads or ad sets."
},
"minimum_counted_arrivals": {
"type": "integer",
"minimum": 50,
"description": "Counted arrivals on the target. At least 100 for a budget increase."
}
},
"description": "Both arrivals and cost conditions must hold over the last 3 complete days in the account timezone. Supply the complete definition when editing.",
"additionalProperties": false
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Create a judging-only Test from 2 to 4 ads in one mirrored Meta ad set. Omit the conversion choice to freeze the workspace default. It records a Plainrouter verdict and never creates a proposal or writes to Meta.
| Argument | Type | Description |
|---|---|---|
| axis* | string | |
| ad_set_id* | string | |
| event_name | string | null | Optional observed conversion choice. Omit for the workspace default. |
| maximum_days | integer | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| member_ad_ids* | array | |
| arrivals_floor | integer | |
| conversion_mode | string | Omit to freeze the workspace default; an explicit event_name always preserves that choice. |
| maximum_spend_minor |
List judging Tests with their frozen conversion definitions, loser pause candidate status and reason, and observed conversion event choices for the authorized workspace and ad account. Results rank variants only within each Test.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| per_page | integer | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 10000000000000000,
"minimum": 1
},
"per_page": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Read one Test, its frozen conversion definition, stored verdict facts, and loser pause candidate status and reason. Spend per recorded conversion compares variants only within this Test.
| Argument | Type | Description |
|---|---|---|
| test_id* | string | The Test ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"test_id"
],
"properties": {
"test_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"maxLength": 26,
"minLength": 26,
"description": "The Test ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Preview policy decisions and execution diffs for a proposed Action batch without writing it.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum complete result actions; the shared JSON byte budget can return fewer. |
| cursor | integer | Continue using next_cursor. Read saved proposal actions with get_action_batch to avoid another write; dry runs repeat the same inputs. |
| actions* | array | |
| evidence* | array | |
| rationale* | string | |
| account_id | integer | |
| workspace_id | integer | |
| target_source* | string | |
| idempotency_key* | string |
Submit a canonical proposal to duplicate a source Meta ad with a different creative asset. In Ask mode every change waits for a person's approval; in Full mode, changes that pass admission and workspace policy run automatically. Policy-allowed copies are always created PAUSED.
| Argument | Type | Description |
|---|---|---|
| asset_id* | string | Asset ID returned by upload-asset or get-creative-library. |
| rationale* | string | Why this new creative variant should be created. |
| source_ad* | string | Numeric Meta ID of the ad to duplicate. |
| account_id | integer | Advertising account ID. Required when the workspace has more than one active account. |
| name_suffix | string | Optional suffix for the copied ad name. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| idempotency_key* | string | Stable key reused when retrying this duplicate proposal. |
Return Meta image and video assets with the ads and last-30-day performance historically associated with each asset.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum assets requested per type; capped at 10 and the projection byte budget. Use pagination to continue. |
| cursor | string | Opaque Meta cursor returned by a previous call. |
| ads_limit | integer | Associated ads per asset, also capped at 30 across the requested asset pages. |
| account_id | integer | Advertising account ID. Required when the workspace has more than one active account. |
| ads_cursor | integer | Continue associated ads using performance.next_cursor, keeping the asset page arguments. |
| asset_type | string | Limit results to images or videos. Defaults to all. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| performance_cursor | string | Continue the provider performance scan using performance_pagination.next_cursor. |
Read the authorized workspace account inventory from the Meta mirror, with optional level, status, parent, and ID cursor filters.
| Argument | Type | Description |
|---|---|---|
| level | string | Limit results to campaign, adset, or ad objects. |
| limit | integer | Maximum complete objects, from 1 to 200; defaults to 25 and may return fewer to fit the JSON budget. Account summary totals are present on every page. |
| adset_id | string | Filter to objects under this parent ad set ID. |
| after_id | integer | Database ID cursor from the previous page; continue with its last object ID. |
| account_id* | integer | Advertising account ID available to the authorized workspace. |
| campaign_id | string | Filter to objects under this parent campaign ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| effective_status | string | Filter by Meta effective status, such as ACTIVE, PAUSED, or ARCHIVED. |
Return the authorized advertising account, workspace, connection, Signal destination, and currently available account capabilities. This read-only inspection tool does not change the account.
| Argument | Type | Description |
|---|---|---|
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Get one proposed action for the authorized workspace and advertising account. counted_evidence contains frozen target figures and coverage captured at proposal time; null means not captured. The figures inform and never gate.
| Argument | Type | Description |
|---|---|---|
| action_id* | string | |
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"action_id"
],
"properties": {
"action_id": {
"type": "string"
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Get a proposed action batch for the authorized workspace and advertising account. Each action’s counted_evidence contains frozen proposal-time target figures and coverage; null means not captured.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| cursor | integer | Continue using next_cursor with the same account and filters. |
| batch_id* | string | |
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"batch_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using next_cursor with the same account and filters."
},
"batch_id": {
"type": "string"
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Get the persisted decision receipt for an authorized proposed action. Receipts can include counted_evidence frozen at proposal time with account-currency values, coverage and the other-currency exclusion.
| Argument | Type | Description |
|---|---|---|
| action_id* | string | |
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"action_id"
],
"properties": {
"action_id": {
"type": "string"
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Get the effective Actions policy for the authorized workspace without creating a policy row.
| Argument | Type | Description |
|---|---|---|
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Return counted arrivals beside Meta outbound clicks for the authorized workspace and selected trailing window. difference is arrivals.value minus claimed_clicks; positive means more arrivals than Meta outbound clicks. conversions.count counts retained logical conversions under the current workspace conversion choices, independently of arrivals and Meta acceptance; the block publishes its selection version, completed local-day period, and availability. purchases.plainrouter_accepted_purchases counts only non-test, observed, attribution-joined Purchases Plainrouter sent and Meta accepted, beside Meta-reported Purchase counts under the account attribution setting, with no purchase gap or status; its eligibility differs from conversions.count, and its account-local window ends the day before Meta's latest purchase read, so it can end earlier than conversions.period; with no purchase read it covers conversions.period and window_start_date and window_end_date are null. An unavailable status from missing Meta data still carries measured arrivals; only the status_message 'No complete retained day is available for this comparison period.' pairs unavailable with arrivals.value 0 by convention, not a measured zero. channel_subset.rows[].arrivals counts consented conversion events by source, not arrivals; these rows are not a breakdown of arrivals.value and need not sum to it. claimed_clicks_source of manual means a person entered the click counts; mixed means differing sources, which may include manual entries or legacy rows with unknown provenance. Unless the destination is inactive, claimed_clicks adds Meta's click counts for each account-timezone day; if any day in the period has a non-zero UTC offset, platform_impressions and platform_spend are null and platform_daily shows not_yet_read. With an inactive destination that still reads Meta, claimed_clicks, platform_impressions and platform_spend are summed over UTC days picked by the account-timezone date labels, so for an account outside UTC they cover a shifted span. Days before 2026-06-29, or not re-read by the daily sync since 2026-09-27, may still hold Meta link clicks or all clicks. basis_note explains how the two counts differ.
| Argument | Type | Description |
|---|
Return Plainrouter-earned conversions by channel, with cost per earned conversion in each spend currency, using stored ad spend. Each currency's cac divides that currency's spend by all earned conversions in the row, so when a row has spend in more than one currency, no single value is its full cost; Meta's claimed cost counts Purchases only. Spend and conversion dates are aligned; touch time does not move spend between days. basis_note explains how the two counts differ.
| Argument | Type | Description |
|---|---|---|
| to | string | Inclusive end of the conversion window. Defaults to the current time. |
| from | string | Inclusive beginning of the conversion window. Defaults to 30 days before the end time. |
| level | string | Channel dimension used for per-channel rows. The broadest level, platform, is the default. |
| model | string | Journey credit model used for earned conversions. |
| lookback | integer | Maximum time between a touch and conversion, in days. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| conversion_kind | string | One conversion stage to count. Trial starts are reported separately from subscriptions. |
Read recorded consent rates and recent consent receipts for the requested authorized workspace. Output schema_version 2 replaces country breakdowns and the country daily dimension with geography (country, US state or Canadian province/territory). Rates cover recorded choices, not unique visitors, over 180 days; geography, language and banner version breakdowns and their daily series show the top 50 values by recorded choices. An independent policy_class breakdown includes Policy not recorded for NULL history. Recent receipts include raw country, nullable region and policy_class, geography and geography_label. This tool does not change data or call advertising APIs.
| Argument | Type | Description |
|---|---|---|
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Read credited conversion journeys for an authorized workspace. Plainrouter counts earned from its own journeys. Earned covers every selected conversion kind; claimed covers Meta Purchases only, possibly in another currency. The two are shown side by side and are never reconciled. The output carries no Plainrouter person or visitor identifiers. UTM labels and ad ids appear exactly as the merchant's links sent them. basis_note explains how the two counts differ.
| Argument | Type | Description |
|---|---|---|
| to | string | Inclusive end of the journey window. Defaults to the current time. |
| from | string | Inclusive beginning of the journey window. Defaults to 30 days before the end time. |
| level | string | Channel dimension used for per-channel rows. The broadest level, platform, is the default. |
| limit | integer | Maximum credited journeys per page. |
| model | string | Journey credit model. |
| cursor | string | Continue the journey page using next_cursor from the previous response. |
| lookback | integer | Maximum time between a touch and conversion, in days. |
Read the latest pre-consent cookie scan for the authorized workspace. Blocked and failed scans report findings as unavailable, never as a clean result. When bot protection blocks the start page, allowlist the PlainRouterScanner user agent before retrying.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| cursor | integer | Continue using next_cursor in the same workspace. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 5,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using next_cursor in the same workspace."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Read weekly distinct optimization-event delivery counts by ad set, campaign or platform from stored data. Plainrouter delivery counts, not Meta's learning status. Test sends excluded; conversion kinds separate. Configurable planning benchmark, unverified live. No provider calls or writes.
| Argument | Type | Description |
|---|---|---|
| to | string | Inclusive event occurrence end; defaults to now. Weeks use UTC occurrence time. |
| from | string | Inclusive event occurrence beginning; defaults to 90 days before to. |
| level | string | |
| model | string | One integer assignment. Default campaign/ad-set membership is the last pre-conversion touch carrying a campaign/ad-set id, not the literal last site touch. First selects the first qualifying touch. |
| lookback | integer | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date-time",
"description": "Inclusive event occurrence end; defaults to now. Weeks use UTC occurrence time."
},
"from": {
"type": "string",
"format": "date-time",
"description": "Inclusive event occurrence beginning; defaults to 90 days before to."
},
"level": {
"enum": [
"platform",
"campaign_id",
"ad_set_id"
],
"type": "string",
"default": "ad_set_id"
},
"model": {
"enum": [
"first",
"last"
],
"type": "string",
"default": "last",
"description": "One integer assignment. Default campaign/ad-set membership is the last pre-conversion touch carrying a campaign/ad-set id, not the literal last site touch. First selects the first qualifying touch."
},
"lookback": {
"enum": [
7,
30,
60,
90
],
"type": "integer",
"default": 90
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Return managed-hostname installation material and first-arrival state for the authorized workspace. Includes ordered SaaS setup steps and owner handoffs. Returns no same-origin forwarding material.
| Argument | Type | Description |
|---|---|---|
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Return counted Plainrouter arrivals beside daily Meta metrics for mirrored campaigns, ad sets and ads. object_metrics contains account-timezone daily comparisons; unmatched_arrivals is one workspace/window count without unknown IDs. Counts are null when the arrivals store is disabled. Optional change history is retention-clamped. basis_note explains how the two counts differ.
| Argument | Type | Description |
|---|---|---|
| ad_id | string | Limit metrics to this ad ID. |
| limit | integer | Maximum rows per collection; byte budgets may return fewer. |
| cursor | string | Continue all three collections using next_cursor with the same filters and include_changes. |
| adset_id | string | Limit metrics to this ad set ID. |
| end_date | string | Inclusive end date in YYYY-MM-DD format. |
| account_id* | integer | Advertising account ID available to the authorized workspace. |
| start_date | string | Inclusive start date in YYYY-MM-DD format. |
| campaign_id | string |
Admissible proposal evidence: reconciliation meta_reported shows Meta dataset event totals beside gateway_verified events Plainrouter sent and Meta accepted. The separate purchases block shows Meta-reported Purchase counts under the account attribution setting beside Plainrouter accepted server-side Purchase counts, with its completed account-local window start and end dates and no purchase gap or status. Includes stored daily Meta spend and delivery metrics. platform_claimed_clicks means Meta outbound clicks. Days before 2026-06-29, or not re-read by the daily sync since 2026-09-27, may still hold Meta link clicks or all clicks. purchases.basis_note explains how the two counts differ. basis_note explains how the two counts differ.
| Argument | Type | Description |
|---|---|---|
| days | integer | Number of reporting days to compare, from 1 to 90. |
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"default": 7,
"maximum": 90,
"minimum": 1,
"description": "Number of reporting days to compare, from 1 to 90."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Diagnostic view of first-party event flow, Meta delivery outcomes, match quality, and reconciliation gaps from Plainrouter stored measurements. Not admissible evidence for spend-affecting proposals. Does not call the Marketing API. Reconciliation compares Meta dataset event totals with events Plainrouter sent and Meta accepted. performance.basis_note explains how the two counts differ.
| Argument | Type | Description |
|---|---|---|
| days | integer | Trailing window in days. One of 7, 30, 90. |
| months | integer | Trailing window of 12 calendar months, in place of days. Offered only where the workspace plan keeps that history and the workspace is set to keep it. |
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"days": {
"enum": [
7,
30,
90
],
"type": "integer",
"default": 7,
"maximum": 90,
"minimum": 7,
"description": "Trailing window in days. One of 7, 30, 90."
},
"months": {
"enum": [
12
],
"type": "integer",
"description": "Trailing window of 12 calendar months, in place of days. Offered only where the workspace plan keeps that history and the workspace is set to keep it."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Read stored conversion delivery outcomes, delivery gaps, retained identity presence, and journey coverage for an authorized workspace. The response uses stored data only and does not call advertising APIs. refused_before_delivery.consent counts undelivered events with consent_basis=severed_measurement, not banner refusals; other undelivered opt-outs and lifecycle events whose checkout lacked consent fall under reason_unknown. Consent rates are 0-1 fractions.
| Argument | Type | Description |
|---|---|---|
| to | string | Inclusive end of the conversion window. Defaults to the current time. |
| from | string | Inclusive beginning of the conversion window. Defaults to 30 days before the end time. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| conversion_kinds | array | Conversion kinds to include; defaults to trial_started and subscribed. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date-time",
"description": "Inclusive end of the conversion window. Defaults to the current time."
},
"from": {
"type": "string",
"format": "date-time",
"description": "Inclusive beginning of the conversion window. Defaults to 30 days before the end time."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"conversion_kinds": {
"type": "array",
"items": {
"enum": [
"trial_started",
"subscribed",
"purchase",
"lead"
],
"type": "string"
},
"default": [
"trial_started",
"subscribed"
],
"maxItems": 4,
"minItems": 1,
"description": "Conversion kinds to include; defaults to trial_started and subscribed.",
"uniqueItems": true
}
}
}Follow stored trial-start cohorts to their first positive payment at 14, 30 and 60 days. Default campaign/ad-set membership is the last pre-trial touch carrying a campaign/ad-set id in the frozen trial journey. Uses integer mature samples and Wilson intervals. Stored data only; no provider calls or writes.
| Argument | Type | Description |
|---|---|---|
| to | string | Inclusive trial-start cohort end; defaults to now. Payments are followed through now. |
| from | string | Inclusive trial-start cohort beginning; defaults to 90 days before to. |
| level | string | |
| model | string | One integer assignment. Default campaign/ad-set membership is the last pre-trial touch carrying a campaign/ad-set id, not the literal last site touch. First selects the first qualifying touch; ad level requires an ad id. |
| lookback | integer | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date-time",
"description": "Inclusive trial-start cohort end; defaults to now. Payments are followed through now."
},
"from": {
"type": "string",
"format": "date-time",
"description": "Inclusive trial-start cohort beginning; defaults to 90 days before to."
},
"level": {
"enum": [
"platform",
"campaign_id",
"ad_set_id",
"ad_id"
],
"type": "string",
"default": "ad_set_id"
},
"model": {
"enum": [
"first",
"last"
],
"type": "string",
"default": "last",
"description": "One integer assignment. Default campaign/ad-set membership is the last pre-trial touch carrying a campaign/ad-set id, not the literal last site touch. First selects the first qualifying touch; ad level requires an ad id."
},
"lookback": {
"enum": [
7,
30,
60,
90
],
"type": "integer",
"default": 90
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}List creatives in the workspace bound to the authenticated execution token.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| cursor | integer | Continue using creatives.next_cursor in the same workspace. |
| per_page | integer | Number of creatives to return per page. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 10000000000000000,
"minimum": 1
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using creatives.next_cursor in the same workspace."
},
"per_page": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Number of creatives to return per page."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Show one creative in the workspace bound to the authenticated execution token.
| Argument | Type | Description |
|---|---|---|
| creative_id* | string | ULID of the creative to show. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"creative_id"
],
"properties": {
"creative_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "ULID of the creative to show."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Set the status of one creative in the workspace bound to the authenticated execution token.
| Argument | Type | Description |
|---|---|---|
| status* | string | Target creative status. |
| creative_id* | string | ULID of the creative to update. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"creative_id",
"status"
],
"properties": {
"status": {
"enum": [
"draft",
"approved",
"retired"
],
"type": "string",
"description": "Target creative status."
},
"creative_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "ULID of the creative to update."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Store one JPEG, PNG, MP4, or QuickTime creative from strict base64 content in the token-bound workspace. When supplying output from an outside tool, set tags.generator, tags.generator_job and, for a variation, tags.parent_creative. Images enter the library by upload or launch.creatives.store-from-url.
| Argument | Type | Description |
|---|---|---|
| tags | object | Optional flat map of up to 32 string tags, including reserved provenance keys. For output from an outside tool set generator (lowercase slug, 1-64 letters, digits or hyphens), generator_job (1-255 printable characters), and parent_creative for a variation (the API id of an existing creative in this workspace). Invalid reserved values return creative_provenance_invalid. Valid values are stored unchanged. |
| mime_type | string | null | Optional caller label accepted only for compatibility and ignored; creative type is derived from the bytes. |
| source_ref | string | null | Optional caller-supplied source reference. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| content_base64* | string | Strict standard base64 creative content, decoded to at most 5 MiB. |
{
"type": "object",
"required": [
"content_base64"
],
"properties": {
"tags": {
"type": "object",
"description": "Optional flat map of up to 32 string tags, including reserved provenance keys. For output from an outside tool set generator (lowercase slug, 1-64 letters, digits or hyphens), generator_job (1-255 printable characters), and parent_creative for a variation (the API id of an existing creative in this workspace). Invalid reserved values return creative_provenance_invalid. Valid values are stored unchanged."
},
"mime_type": {
"type": [
"string",
"null"
],
"maxLength": 255,
"description": "Optional caller label accepted only for compatibility and ignored; creative type is derived from the bytes."
},
"source_ref": {
"type": [
"string",
"null"
],
"maxLength": 255,
"description": "Optional caller-supplied source reference."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"content_base64": {
"type": "string",
"description": "Strict standard base64 creative content, decoded to at most 5 MiB."
}
}
}Fetch and store one creative from a vetted HTTPS URL in the token-bound workspace. When supplying output from an outside tool, set tags.generator, tags.generator_job and, for a variation, tags.parent_creative. Images enter the library by upload or launch.creatives.store-from-url.
| Argument | Type | Description |
|---|---|---|
| url* | string | HTTPS URL of the creative to fetch. |
| tags | object | Optional flat map of up to 32 string tags, including reserved provenance keys. For output from an outside tool set generator (lowercase slug, 1-64 letters, digits or hyphens), generator_job (1-255 printable characters), and parent_creative for a variation (the API id of an existing creative in this workspace). Invalid reserved values return creative_provenance_invalid. Valid values are stored unchanged. |
| source_ref | string | null | Optional caller-supplied source reference. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "HTTPS URL of the creative to fetch."
},
"tags": {
"type": "object",
"description": "Optional flat map of up to 32 string tags, including reserved provenance keys. For output from an outside tool set generator (lowercase slug, 1-64 letters, digits or hyphens), generator_job (1-255 printable characters), and parent_creative for a variation (the API id of an existing creative in this workspace). Invalid reserved values return creative_provenance_invalid. Valid values are stored unchanged."
},
"source_ref": {
"type": [
"string",
"null"
],
"maxLength": 255,
"description": "Optional caller-supplied source reference."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Copy a failed plan to a new draft with the same content. Validate and submit the draft afresh; the failed plan and its history stay unchanged.
| Argument | Type | Description |
|---|---|---|
| plan_id* | string | The deployment plan ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"plan_id"
],
"properties": {
"plan_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "The deployment plan ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Create a deployment plan for the approved ad account.
| Argument | Type | Description |
|---|---|---|
| copy* | object | |
| name | string | null | |
| currency* | string | |
| platform* | string | |
| ad_set_ref | string | null | |
| ad_set_spec | object | null | |
| budget_type* | string | |
| campaign_ref | string | null | |
| creative_ids | array | |
| landing_page* | string | |
| workspace_id |
Execute one deployment plan in the workspace and ad account bound to the execution token; requires the review_version returned by the plan read you acted on. Changed plans are refused before any intent or staging; identical intent_key and review_version retries replay. All provider mutations are proposed through Actions.
| Argument | Type | Description |
|---|---|---|
| plan_id* | string | The deployment plan ID. |
| intent_key | string | null | An optional idempotency key for this execution. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| review_version* | string | The review_version from the plan read you acted on. Reload and review if the plan changed. |
{
"type": "object",
"required": [
"plan_id",
"review_version"
],
"properties": {
"plan_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "The deployment plan ID."
},
"intent_key": {
"type": [
"string",
"null"
],
"maxLength": 240,
"description": "An optional idempotency key for this execution."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"review_version": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "The review_version from the plan read you acted on. Reload and review if the plan changed."
}
}
}List deployment plans for the approved ad account, including each current review_version to pass when executing the reviewed plan.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| cursor | integer | Continue using plans.next_cursor with the same account. |
| per_page | integer | string | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 10000000000000000,
"minimum": 1
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using plans.next_cursor with the same account."
},
"per_page": {
"type": [
"integer",
"string"
]
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Read one deployment plan and its current review_version and latest launch-intent status in the workspace and ad account bound to the execution token.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| cursor | integer | Continue plan creatives using plan.next_cursor. |
| plan_id* | string | The deployment plan ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"plan_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 5,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue plan creatives using plan.next_cursor."
},
"plan_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "The deployment plan ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Update a deployment plan for the approved ad account.
| Argument | Type | Description |
|---|---|---|
| copy | object | |
| name | string | null | |
| plan_id* | string | The deployment plan ID. |
| currency | string | |
| platform | string | |
| ad_set_ref | string | null | |
| ad_set_spec | object | null | |
| budget_type | string | |
| campaign_ref | string | null | |
| creative_ids | array | |
| landing_page | string | |
Validate a deployment plan for the approved ad account.
| Argument | Type | Description |
|---|---|---|
| plan_id* | string | The deployment plan ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"plan_id"
],
"properties": {
"plan_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "The deployment plan ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}List proposed actions for the authorized workspace and advertising account.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| limit | integer | |
| cursor | integer | Continue using next_cursor with the same account and filters. |
| status | string | |
| account_id | integer | Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 10000000000000000,
"minimum": 1
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using next_cursor with the same account and filters."
},
"status": {
"enum": [
"pending",
"approved_without_execution",
"rejected",
"executing",
"executed_pending_verification",
"compensating",
"measuring",
"verified",
"failed",
"execution_uncertain",
"rolled_back",
"blocked"
],
"type": "string"
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}List the workspaces and effective access tiers in this credential scope.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum workspaces; the projection budget may return fewer. |
| cursor | integer | Continue using next_cursor in this credential scope. |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum workspaces; the projection budget may return fewer."
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using next_cursor in this credential scope."
}
}
}Propose a batch of budget, status, upload, or creative-duplication actions for the approved ad account. In Ask, every policy-allowed change waits for a person to approve it. In Full, policy-allowed changes run automatically. Rule violations are blocked and shown in the Inbox, and cannot be approved. The execution kill switch stops further writes and never undoes a landed change. Dispatch still requires a live grant, an account in the workspace, and no duplicate write. Legacy set_status and adjust_budget never run. Meta target proposals freeze counted_evidence over the last seven completed account-local days for display only. Evidence may cite get_inventory_metrics leaf fields for the proposed target: Meta inline link clicks, counted arrivals and Purchase count/value at that target’s own level. Spend, impressions, child-object rows, containers, ratios and other action types are refused.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum complete result actions; the shared JSON byte budget can return fewer. |
| cursor | integer | Continue using next_cursor. Read saved proposal actions with get_action_batch to avoid another write; dry runs repeat the same inputs. |
| actions* | array | |
| evidence* | array | |
| rationale* | string | |
| account_id |
Revoke an active workspace grant. The caller must hold the revoke_grant scope in the same workspace or be the human delegator of the granted agent.
| Argument | Type | Description |
|---|---|---|
| grant_id* | string | The ULID of the grant to revoke. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"grant_id"
],
"properties": {
"grant_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The ULID of the grant to revoke."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Report a bug or a missing capability you hit while using this server. Say what you were trying to do and what happened. Nothing in the account changes and no reply is sent here.
| Argument | Type | Description |
|---|---|---|
| kind* | string | |
| message* | string | |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"required": [
"kind",
"message"
],
"properties": {
"kind": {
"enum": [
"bug",
"missing_capability",
"other"
],
"type": "string"
},
"message": {
"type": "string",
"maxLength": 4000,
"minLength": 1
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}Stage a JPEG/PNG image and submit a canonical upload action through workspace policy. In Ask mode every change waits for a person's approval; in Full mode, changes that pass admission and workspace policy run automatically.
| Argument | Type | Description |
|---|---|---|
| filename* | string | Bare filename with a matching .jpg, .jpeg, or .png extension, such as spring-hero.jpg. Path separators are rejected: send a name, not a path. The asset is never written to a filesystem path built from this value. |
| rationale* | string | Why this asset should be added to the creative library. |
| account_id | integer | Advertising account ID. Required when the workspace has more than one active account. |
| asset_type* | string | The creative asset type. Images only. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| content_base64 | string | Raw base64 content for image uploads. Do not use a data URI prefix. |
| idempotency_key* | string |
Send one idempotent, identity-free test event through server-side Signal ingestion for the authorized workspace. A receipt confirms the ledger received it; it is not evidence of a real arrival and does not complete onboarding. No spend capability. It is never sent to Meta.
| Argument | Type | Description |
|---|---|---|
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}| string | null |
| Optional positive whole number of Meta minor units in the selected account currency, using the same unit scale as Launch plan budget_amount_minor; the string form supports up to 18 digits. |
| minimum_conversions | integer |
| platform_ad_account_id* | integer |
{
"type": "object",
"required": [
"platform_ad_account_id",
"ad_set_id",
"member_ad_ids",
"axis"
],
"properties": {
"axis": {
"enum": [
"hook",
"angle",
"visual",
"offer",
"format",
"landing"
],
"type": "string"
},
"ad_set_id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"event_name": {
"type": [
"string",
"null"
],
"maxLength": 255,
"minLength": 1,
"description": "Optional observed conversion choice. Omit for the workspace default."
},
"maximum_days": {
"type": "integer",
"maximum": 30,
"minimum": 3
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"member_ad_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"maxItems": 4,
"minItems": 2,
"uniqueItems": true
},
"arrivals_floor": {
"type": "integer",
"minimum": 50
},
"conversion_mode": {
"enum": [
"workspace_default",
"explicit"
],
"type": "string",
"description": "Omit to freeze the workspace default; an explicit event_name always preserves that choice."
},
"maximum_spend_minor": {
"type": [
"string",
"null"
],
"pattern": "^[1-9][0-9]{0,17}$",
"description": "Optional positive whole number of Meta minor units in the selected account currency, using the same unit scale as Launch plan budget_amount_minor; the string form supports up to 18 digits."
},
"minimum_conversions": {
"type": "integer",
"minimum": 1
},
"platform_ad_account_id": {
"type": "integer",
"minimum": 1
}
}
}{
"type": "object",
"required": [
"actions",
"rationale",
"idempotency_key",
"evidence",
"target_source"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum complete result actions; the shared JSON byte budget can return fewer."
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using next_cursor. Read saved proposal actions with get_action_batch to avoid another write; dry runs repeat the same inputs."
},
"actions": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"increase_budget"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"new_daily_budget_minor"
],
"properties": {
"new_daily_budget_minor": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"decrease_budget"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"new_daily_budget_minor"
],
"properties": {
"new_daily_budget_minor": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"pause"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"resume"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"replace_creative"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"shift_spend"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"rollback"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"create_campaign"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"create_ad_set"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"create_ad"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"upload_asset"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"staged_asset_id",
"asset_type",
"filename",
"content_sha256"
],
"properties": {
"filename": {
"type": "string",
"maxLength": 255
},
"mime_type": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"asset_type": {
"enum": [
"image"
],
"type": "string"
},
"size_bytes": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"content_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"staged_asset_id": {
"type": "string",
"pattern": "^stage_[a-f0-9]{40}$",
"maxLength": 255
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"adjust_budget"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"new_daily_budget_minor"
],
"properties": {
"new_daily_budget_minor": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"set_status"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"duplicate_ad_with_creative"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"asset_id",
"status"
],
"properties": {
"status": {
"enum": [
"paused"
],
"type": "string"
},
"asset_id": {
"type": "string",
"pattern": "^(image|video):.+$",
"maxLength": 255
},
"name_suffix": {
"type": [
"string",
"null"
],
"maxLength": 100
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
}
]
},
"maxItems": 25,
"minItems": 1
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"required": [
"source_tool",
"fields_used"
],
"properties": {
"fields_used": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 50,
"minItems": 1
},
"source_tool": {
"enum": [
"get_account_state",
"get_signal_health",
"get_performance",
"get_inventory_metrics",
"get-creative-library",
"staged-asset-manifest"
],
"type": "string"
},
"action_index": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"maxItems": 3,
"minItems": 1
},
"rationale": {
"type": "string",
"maxLength": 4000
},
"account_id": {
"type": "integer",
"minimum": 1
},
"workspace_id": {
"type": "integer",
"minimum": 1
},
"target_source": {
"enum": [
"human_supplied"
],
"type": "string"
},
"idempotency_key": {
"type": "string",
"maxLength": 64
}
}
}{
"type": "object",
"required": [
"source_ad",
"asset_id",
"rationale",
"idempotency_key"
],
"properties": {
"asset_id": {
"type": "string",
"pattern": "^(image|video):.+$",
"description": "Asset ID returned by upload-asset or get-creative-library."
},
"rationale": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "Why this new creative variant should be created."
},
"source_ad": {
"type": "string",
"pattern": "^\\d+$",
"description": "Numeric Meta ID of the ad to duplicate."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Required when the workspace has more than one active account."
},
"name_suffix": {
"type": "string",
"maxLength": 100,
"description": "Optional suffix for the copied ad name."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"description": "Stable key reused when retrying this duplicate proposal."
}
}
}{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum assets requested per type; capped at 10 and the projection byte budget. Use pagination to continue."
},
"cursor": {
"type": "string",
"description": "Opaque Meta cursor returned by a previous call."
},
"ads_limit": {
"type": "integer",
"default": 3,
"maximum": 10,
"minimum": 1,
"description": "Associated ads per asset, also capped at 30 across the requested asset pages."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Required when the workspace has more than one active account."
},
"ads_cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue associated ads using performance.next_cursor, keeping the asset page arguments."
},
"asset_type": {
"enum": [
"all",
"image",
"video"
],
"type": "string",
"default": "all",
"description": "Limit results to images or videos. Defaults to all."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"performance_cursor": {
"type": "string",
"description": "Continue the provider performance scan using performance_pagination.next_cursor."
}
}
}{
"type": "object",
"required": [
"account_id"
],
"properties": {
"level": {
"enum": [
"campaign",
"adset",
"ad"
],
"type": "string",
"description": "Limit results to campaign, adset, or ad objects."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 200,
"minimum": 1,
"description": "Maximum complete objects, from 1 to 200; defaults to 25 and may return fewer to fit the JSON budget. Account summary totals are present on every page."
},
"adset_id": {
"type": "string",
"description": "Filter to objects under this parent ad set ID."
},
"after_id": {
"type": "integer",
"minimum": 1,
"description": "Database ID cursor from the previous page; continue with its last object ID."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID available to the authorized workspace."
},
"campaign_id": {
"type": "string",
"description": "Filter to objects under this parent campaign ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"effective_status": {
"type": "string",
"description": "Filter by Meta effective status, such as ACTIVE, PAUSED, or ARCHIVED."
}
}
}| days | integer | Trailing window in days. One of 7, 30, 90. |
| months | integer | Trailing window of 12 calendar months, in place of days. Offered only where the workspace plan keeps that history and the workspace is set to keep it. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
{
"type": "object",
"properties": {
"days": {
"enum": [
7,
30,
90
],
"type": "integer",
"default": 7,
"maximum": 90,
"minimum": 7,
"description": "Trailing window in days. One of 7, 30, 90."
},
"months": {
"enum": [
12
],
"type": "integer",
"description": "Trailing window of 12 calendar months, in place of days. Offered only where the workspace plan keeps that history and the workspace is set to keep it."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
}
}
}{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date-time",
"description": "Inclusive end of the conversion window. Defaults to the current time."
},
"from": {
"type": "string",
"format": "date-time",
"description": "Inclusive beginning of the conversion window. Defaults to 30 days before the end time."
},
"level": {
"enum": [
"platform",
"campaign_id",
"ad_set_id",
"ad_id",
"utm_source",
"utm_medium",
"utm_campaign"
],
"type": "string",
"default": "platform",
"description": "Channel dimension used for per-channel rows. The broadest level, platform, is the default."
},
"model": {
"enum": [
"position_based",
"first",
"last",
"linear"
],
"type": "string",
"default": "position_based",
"description": "Journey credit model used for earned conversions."
},
"lookback": {
"enum": [
7,
30,
60,
90
],
"type": "integer",
"default": 90,
"description": "Maximum time between a touch and conversion, in days."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"conversion_kind": {
"enum": [
"subscribed",
"purchase",
"trial_started"
],
"type": "string",
"default": "subscribed",
"description": "One conversion stage to count. Trial starts are reported separately from subscriptions."
}
}
}| workspace_id |
| integer |
| Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| conversion_kinds | array | Conversion kinds to count; defaults to subscribed and one-off purchase conversions. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"format": "date-time",
"description": "Inclusive end of the journey window. Defaults to the current time."
},
"from": {
"type": "string",
"format": "date-time",
"description": "Inclusive beginning of the journey window. Defaults to 30 days before the end time."
},
"level": {
"enum": [
"platform",
"campaign_id",
"ad_set_id",
"ad_id",
"utm_source",
"utm_medium",
"utm_campaign"
],
"type": "string",
"default": "platform",
"description": "Channel dimension used for per-channel rows. The broadest level, platform, is the default."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1,
"description": "Maximum credited journeys per page."
},
"model": {
"enum": [
"position_based",
"first",
"last",
"linear"
],
"type": "string",
"default": "position_based",
"description": "Journey credit model."
},
"cursor": {
"type": "string",
"description": "Continue the journey page using next_cursor from the previous response."
},
"lookback": {
"enum": [
7,
30,
60,
90
],
"type": "integer",
"default": 90,
"description": "Maximum time between a touch and conversion, in days."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"conversion_kinds": {
"type": "array",
"items": {
"enum": [
"subscribed",
"trial_started",
"purchase"
],
"type": "string"
},
"default": [
"subscribed",
"purchase"
],
"maxItems": 3,
"minItems": 1,
"description": "Conversion kinds to count; defaults to subscribed and one-off purchase conversions.",
"uniqueItems": true
}
}
}| Limit metrics to this campaign ID. |
| workspace_id | integer | Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| include_changes | boolean | Include object change history within the effective date window. |
{
"type": "object",
"required": [
"account_id"
],
"properties": {
"ad_id": {
"type": "string",
"description": "Limit metrics to this ad ID."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum rows per collection; byte budgets may return fewer."
},
"cursor": {
"type": "string",
"description": "Continue all three collections using next_cursor with the same filters and include_changes."
},
"adset_id": {
"type": "string",
"description": "Limit metrics to this ad set ID."
},
"end_date": {
"type": "string",
"description": "Inclusive end date in YYYY-MM-DD format."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID available to the authorized workspace."
},
"start_date": {
"type": "string",
"description": "Inclusive start date in YYYY-MM-DD format."
},
"campaign_id": {
"type": "string",
"description": "Limit metrics to this campaign ID."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"include_changes": {
"type": "boolean",
"default": false,
"description": "Include object change history within the effective date window."
}
}
}| integer |
| Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| campaign_spec | object | null |
| utm_policy_name | string | null |
| creative_overrides | array |
| naming_policy_name | string | null |
| budget_amount_minor* | integer |
| platform_ad_account_id* | integer |
{
"type": "object",
"required": [
"platform_ad_account_id",
"platform",
"budget_type",
"budget_amount_minor",
"currency",
"copy",
"landing_page"
],
"properties": {
"copy": {
"type": "object",
"required": [
"primary_text",
"headline",
"description",
"cta"
],
"properties": {
"cta": {
"enum": [
"learn_more",
"shop_now",
"sign_up"
],
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"primary_text": {
"type": "string"
}
}
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3
},
"platform": {
"enum": [
"google",
"meta",
"microsoft"
],
"type": "string"
},
"ad_set_ref": {
"type": [
"string",
"null"
]
},
"ad_set_spec": {
"type": [
"object",
"null"
]
},
"budget_type": {
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"campaign_ref": {
"type": [
"string",
"null"
]
},
"creative_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"landing_page": {
"type": "string",
"format": "uri"
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"campaign_spec": {
"type": [
"object",
"null"
]
},
"utm_policy_name": {
"type": [
"string",
"null"
]
},
"creative_overrides": {
"type": "array",
"items": {
"type": "object",
"required": [
"creative_id"
],
"properties": {
"copy": {
"type": [
"object",
"null"
],
"required": [
"primary_text",
"headline",
"description",
"cta"
],
"properties": {
"cta": {
"enum": [
"learn_more",
"shop_now",
"sign_up"
],
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"primary_text": {
"type": "string"
}
}
},
"creative_id": {
"type": "string",
"description": "The ULID of a creative included in this plan."
},
"landing_page": {
"type": [
"string",
"null"
],
"format": "uri",
"maxLength": 2048
}
}
}
},
"naming_policy_name": {
"type": [
"string",
"null"
]
},
"budget_amount_minor": {
"type": "integer",
"minimum": 0
},
"platform_ad_account_id": {
"type": "integer",
"minimum": 1
}
}
}| workspace_id |
| integer |
| Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces. |
| campaign_spec | object | null |
| utm_policy_name | string | null |
| creative_overrides | array |
| naming_policy_name | string | null |
| budget_amount_minor | integer |
| platform_ad_account_id | integer |
{
"type": "object",
"required": [
"plan_id"
],
"properties": {
"copy": {
"type": "object",
"required": [
"primary_text",
"headline",
"description",
"cta"
],
"properties": {
"cta": {
"enum": [
"learn_more",
"shop_now",
"sign_up"
],
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"primary_text": {
"type": "string"
}
}
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"plan_id": {
"type": "string",
"pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
"description": "The deployment plan ID."
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3
},
"platform": {
"enum": [
"google",
"meta",
"microsoft"
],
"type": "string"
},
"ad_set_ref": {
"type": [
"string",
"null"
]
},
"ad_set_spec": {
"type": [
"object",
"null"
]
},
"budget_type": {
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"campaign_ref": {
"type": [
"string",
"null"
]
},
"creative_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"landing_page": {
"type": "string",
"format": "uri"
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"campaign_spec": {
"type": [
"object",
"null"
]
},
"utm_policy_name": {
"type": [
"string",
"null"
]
},
"creative_overrides": {
"type": "array",
"items": {
"type": "object",
"required": [
"creative_id"
],
"properties": {
"copy": {
"type": [
"object",
"null"
],
"required": [
"primary_text",
"headline",
"description",
"cta"
],
"properties": {
"cta": {
"enum": [
"learn_more",
"shop_now",
"sign_up"
],
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"primary_text": {
"type": "string"
}
}
},
"creative_id": {
"type": "string",
"description": "The ULID of a creative included in this plan."
},
"landing_page": {
"type": [
"string",
"null"
],
"format": "uri",
"maxLength": 2048
}
}
}
},
"naming_policy_name": {
"type": [
"string",
"null"
]
},
"budget_amount_minor": {
"type": "integer",
"minimum": 0
},
"platform_ad_account_id": {
"type": "integer",
"minimum": 1
}
}
}| integer |
| workspace_id | integer |
| target_source* | string |
| idempotency_key* | string |
{
"type": "object",
"required": [
"actions",
"rationale",
"idempotency_key",
"evidence",
"target_source"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum complete result actions; the shared JSON byte budget can return fewer."
},
"cursor": {
"type": "integer",
"minimum": 0,
"description": "Continue using next_cursor. Read saved proposal actions with get_action_batch to avoid another write; dry runs repeat the same inputs."
},
"actions": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"increase_budget"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"new_daily_budget_minor"
],
"properties": {
"new_daily_budget_minor": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"decrease_budget"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"new_daily_budget_minor"
],
"properties": {
"new_daily_budget_minor": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"pause"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"resume"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9]+$",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"replace_creative"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"shift_spend"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"rollback"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"create_campaign"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"create_ad_set"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"create_ad"
],
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"upload_asset"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"staged_asset_id",
"asset_type",
"filename",
"content_sha256"
],
"properties": {
"filename": {
"type": "string",
"maxLength": 255
},
"mime_type": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"asset_type": {
"enum": [
"image"
],
"type": "string"
},
"size_bytes": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"content_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"staged_asset_id": {
"type": "string",
"pattern": "^stage_[a-f0-9]{40}$",
"maxLength": 255
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"adjust_budget"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"new_daily_budget_minor"
],
"properties": {
"new_daily_budget_minor": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"set_status"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
},
{
"type": "object",
"required": [
"type",
"target_entity",
"params",
"rationale"
],
"properties": {
"type": {
"enum": [
"duplicate_ad_with_creative"
],
"type": "string"
},
"params": {
"type": "object",
"required": [
"asset_id",
"status"
],
"properties": {
"status": {
"enum": [
"paused"
],
"type": "string"
},
"asset_id": {
"type": "string",
"pattern": "^(image|video):.+$",
"maxLength": 255
},
"name_suffix": {
"type": [
"string",
"null"
],
"maxLength": 100
}
},
"additionalProperties": false
},
"rationale": {
"type": "string",
"maxLength": 2000
},
"target_entity": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"type": {
"enum": [
"ad_account",
"campaign",
"ad_set",
"ad"
],
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
}
}
]
},
"maxItems": 25,
"minItems": 1
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"required": [
"source_tool",
"fields_used"
],
"properties": {
"fields_used": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 50,
"minItems": 1
},
"source_tool": {
"enum": [
"get_account_state",
"get_signal_health",
"get_performance",
"get_inventory_metrics",
"get-creative-library",
"staged-asset-manifest"
],
"type": "string"
},
"action_index": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"maxItems": 3,
"minItems": 1
},
"rationale": {
"type": "string",
"maxLength": 4000
},
"account_id": {
"type": "integer",
"minimum": 1
},
"workspace_id": {
"type": "integer",
"minimum": 1
},
"target_source": {
"enum": [
"human_supplied"
],
"type": "string"
},
"idempotency_key": {
"type": "string",
"maxLength": 64
}
}
}| Stable key reused when retrying this upload proposal. |
{
"type": "object",
"required": [
"asset_type",
"filename",
"rationale",
"idempotency_key"
],
"properties": {
"filename": {
"type": "string",
"maxLength": 100,
"description": "Bare filename with a matching .jpg, .jpeg, or .png extension, such as spring-hero.jpg. Path separators are rejected: send a name, not a path. The asset is never written to a filesystem path built from this value."
},
"rationale": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "Why this asset should be added to the creative library."
},
"account_id": {
"type": "integer",
"minimum": 1,
"description": "Advertising account ID. Required when the workspace has more than one active account."
},
"asset_type": {
"enum": [
"image"
],
"type": "string",
"description": "The creative asset type. Images only."
},
"workspace_id": {
"type": "integer",
"minimum": 1,
"description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces."
},
"content_base64": {
"type": "string",
"description": "Raw base64 content for image uploads. Do not use a data URI prefix."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"description": "Stable key reused when retrying this upload proposal."
}
}
}