- Multiple conditions with AND/OR: Use
conditionsarray withconditions_logic: "AND"or"OR" - Consecutive days: Add
consecutive_days: 3to only trigger after 3 days in a row - Relative thresholds: Set
threshold_type: "relative"withthreshold_multiplier: 1.5to mean “50% above average” - % change detection: Use
operator: "changes_by"withdirection: "decrease"andthreshold: 30for “dropped 30%” - Campaign targeting: Use
campaign_idsto monitor specific campaigns only - Auto-actions (coming soon):
auto_action: "pause_campaign"or"increase_budget"withauto_action_value: 20
- Simple: “Alert me if ROAS drops below 2” → metric: “roas”, operator: “less_than”, threshold: 2.0
- Consecutive days: “Alert if CPA exceeds $50 for 3 days straight” → metric: “cpa”, operator: “greater_than”, threshold: 50, consecutive_days: 3
-
Compound AND: “Alert if CTR
<0.8% AND spend > $200” → conditions: [{metric: "ctr", operator: "less_than", threshold: 0.8},{metric: "spend", operator: "greater_than", threshold: 200}], conditions_logic: “AND” - Relative: “Alert if CPA goes 50% above my 30-day average” → metric: “cpa”, operator: “greater_than”, threshold_type: “relative”, threshold_multiplier: 1.5, threshold_timeframe: “last_30d”
- % drop: “Notify me if cost per lead drops 30% in a day” → metric: “cost_per_lead”, operator: “changes_by”, threshold: 30, direction: “decrease”, timeframe: “vs_previous_day”
- If user doesn’t specify an email for alerts, ASK them. Do not guess.
- If user doesn’t specify platforms, default to all their connected platforms.
- If user doesn’t specify campaigns, default to all campaigns.
- Do not assume timeframe — ask if unclear.
- Do not assume threshold values — ask if the user doesn’t specify a number.
- ROAS monitors are skipped on traffic/awareness/engagement campaigns automatically.
- CPA monitors are skipped on campaigns with zero conversions automatically.
OpenAPI
/api-reference/openapi.json post /api/v1/tools/create_monitor/execute
openapi: 3.1.0
info:
contact:
email: [email protected]
name: ADSMCP Support
description: >-
REST endpoints for every ADSMCP tool. Same surface as the MCP server, over
plain HTTP for consumers that can't speak SSE (n8n, Zapier, Make, curl, any
language's HTTP client).
## Envelope
Every request wraps tool-specific input in an `arguments` object:
```json
{ "arguments": { <tool-specific fields> } }
```
Every response wraps the result in either a success envelope (`success:
true`, `data: {...}`) or an error envelope (`success: false`, `error:
"..."`, `is_error: true`).
## Authentication
Pass your API key as `Authorization: Bearer sk_live_...` on every request.
Generate keys at https://adsmcp.si/dashboard/api-tokens.
## Quota & billing
Every successful billable call decrements your monthly tool-call allowance.
The current counter is attached to every 200 response under `data.quota`:
```json
"quota": { "used": 42, "limit": 150, "tier": "plus", "period_end":
"2026-05-01" }
```
When the limit is hit, the API returns HTTP 402 with a full `quota` block
including `upgrade_url`. Read-only diagnostic tools (`get_usage_status`,
`list_connected_accounts`, `get_connections_status`) are exempt and never
consume quota.
## Idempotency
Write operations accept an `Idempotency-Key: <uuid>` header. A repeated call
with the same key returns the cached result rather than executing twice.
**Strongly recommended for n8n, Zapier, and any retry-prone client** — it
prevents duplicate campaigns when networks misbehave. Generate a fresh UUID
per logical operation (not per retry).
## Multi-account users
Customers with multiple connected accounts on the same platform (e.g. an
agency with 10 Meta ad accounts) must specify which account to use via
`ad_account_id`, `customer_id`, `advertiser_id`, or `account_id` depending
on the platform. Omitting it returns HTTP 400 with a list of valid account
IDs. See `list_connected_accounts` to discover available IDs.
## HTTP status codes
- `200` — success (parse `data`)
- `400` — tool-level error (surface `error` to users)
- `401` — bad/missing API key
- `402` — ADSMCP quota exhausted
- `404` — unknown tool name
- `429` — upstream ad platform rate-limited us (Meta/Google/etc.) — retry
with backoff
- `500` — server error, report to support
## Streaming
This endpoint is plain request-response JSON. There is **no SSE, no chunked
streaming**. Safe to use from n8n Cloud's HTTP Request node, Zapier
Webhooks, Make HTTP module, curl, and every mainstream HTTP library.
title: ADSMCP REST API
version: 1.0.0
servers:
- description: Production
url: https://api.adsmcp.si
security: []
tags:
- description: Audit tools
name: audit
- description: General (Account Management) tools
name: general
- description: Google Ads tools
name: google-ads
- description: LinkedIn Ads tools
name: linkedin-ads
- description: Meta Ads tools
name: meta-ads
- description: Monitoring & Reporting tools
name: monitoring
- description: TikTok Ads tools
name: tiktok-ads
paths:
/api/v1/tools/create_monitor/execute:
post:
tags:
- monitoring
summary: Create Monitor
description: >-
Create a monitoring alert for your campaigns. Checked daily.
**Supported metrics:** roas, ctr, cpc, cpa, cpm, cpv, spend,
conversions, impressions, clicks, cost_per_lead, conversion_rate,
budget_utilization, video_views, engagement_rate
**Operators:** less_than, greater_than, less_than_or_equal,
greater_than_or_equal, changes_by
**Advanced features:**
- **Multiple conditions with AND/OR:** Use `conditions` array with
`conditions_logic: "AND"` or `"OR"`
- **Consecutive days:** Add `consecutive_days: 3` to only trigger after
3 days in a row
- **Relative thresholds:** Set `threshold_type: "relative"` with
`threshold_multiplier: 1.5` to mean "50% above average"
- **% change detection:** Use `operator: "changes_by"` with `direction:
"decrease"` and `threshold: 30` for "dropped 30%"
- **Campaign targeting:** Use `campaign_ids` to monitor specific
campaigns only
- **Auto-actions (coming soon):** `auto_action: "pause_campaign"` or
`"increase_budget"` with `auto_action_value: 20`
**Examples:**
1. Simple: "Alert me if ROAS drops below 2"
→ metric: "roas", operator: "less_than", threshold: 2.0
2. Consecutive days: "Alert if CPA exceeds $50 for 3 days straight"
→ metric: "cpa", operator: "greater_than", threshold: 50,
consecutive_days: 3
3. Compound AND: "Alert if CTR `<` 0.8% AND spend > $200"
→ conditions: [
`{metric: "ctr", operator: "less_than", threshold: 0.8}`,
`{metric: "spend", operator: "greater_than", threshold: 200}`
], conditions_logic: "AND"
4. Relative: "Alert if CPA goes 50% above my 30-day average"
→ metric: "cpa", operator: "greater_than", threshold_type: "relative",
threshold_multiplier: 1.5, threshold_timeframe: "last_30d"
5. % drop: "Notify me if cost per lead drops 30% in a day"
→ metric: "cost_per_lead", operator: "changes_by", threshold: 30,
direction: "decrease", timeframe: "vs_previous_day"
**IMPORTANT:**
- If user doesn't specify an email for alerts, ASK them. Do not guess.
- If user doesn't specify platforms, default to all their connected
platforms.
- If user doesn't specify campaigns, default to all campaigns.
- Do not assume timeframe — ask if unclear.
- Do not assume threshold values — ask if the user doesn't specify a
number.
- ROAS monitors are skipped on traffic/awareness/engagement campaigns
automatically.
- CPA monitors are skipped on campaigns with zero conversions
automatically.
operationId: execute_create_monitor
parameters:
- description: >-
Client-generated UUID to make writes idempotent. Strongly
recommended for write tools. A repeat call with the same key returns
the cached result instead of re-executing. Example:
550e8400-e29b-41d4-a716-446655440000
example: 550e8400-e29b-41d4-a716-446655440000
in: header
name: Idempotency-Key
required: false
schema:
format: uuid
type: string
requestBody:
content:
application/json:
example:
arguments:
conditions:
- consecutive_days: 1
direction: string
metric: string
operator: string
threshold: 1
threshold_multiplier: 1
threshold_timeframe: string
threshold_type: string
timeframe: string
conditions_logic: AND
metric: string
monitor_type: performance_drop
name: string
operator: string
threshold: 1
schema:
properties:
arguments:
description: Input for creating a monitoring alert.
properties:
alert_destination:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Where to send alerts: email address, Slack webhook URL,
etc. If not provided, uses the user's account email.
title: Alert Destination
alert_method:
anyOf:
- type: string
- type: 'null'
default: email
description: >-
How to notify: 'email', 'slack', 'webhook'. Default:
email.
title: Alert Method
auto_action:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Automatic action when triggered: 'pause_campaign',
'increase_budget', 'decrease_budget', 'notify_only'.
Default: notify_only (no automatic changes).
title: Auto Action
auto_action_value:
anyOf:
- type: number
- type: 'null'
default: null
description: >-
Value for auto-action: percentage for budget changes
(e.g., 20 for +20%), ignored for pause/notify.
title: Auto Action Value
campaign_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
default: null
description: >-
Specific campaign IDs to monitor. Default: all
campaigns. Get IDs from
list_campaigns/list_meta_campaigns tools.
title: Campaign Ids
check_frequency:
anyOf:
- type: string
- type: 'null'
default: daily
description: >-
How often to check: 'daily' — checks once per day using
data through yesterday. This is the only available
frequency currently.
title: Check Frequency
conditions:
anyOf:
- items:
$ref: >-
#/components/schemas/execute_create_monitor_MonitorConditionInput
type: array
- type: 'null'
default: null
description: >-
List of conditions. Multiple conditions are evaluated
with AND logic by default. For OR logic, set
conditions_logic='OR'. If not provided, use the
single-condition fields (metric, operator, threshold)
below.
title: Conditions
conditions_logic:
anyOf:
- type: string
- type: 'null'
default: AND
description: >-
How multiple conditions combine: 'AND' (all must be
true) or 'OR' (any must be true). Default: 'AND'.
title: Conditions Logic
consecutive_days:
anyOf:
- type: integer
- type: 'null'
default: null
description: Single condition consecutive days (shorthand).
title: Consecutive Days
metric:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Single condition metric (shorthand). Use 'conditions'
array for multiple conditions.
title: Metric
monitor_type:
anyOf:
- type: string
- type: 'null'
default: performance_drop
description: >-
Type: 'performance_drop', 'budget_pace',
'anomaly_detection', 'spend_threshold',
'conversion_tracking'
title: Monitor Type
name:
description: >-
Name for this alert (e.g., 'High CPA Auto-Pause', 'ROAS
Scaling Rule')
title: Name
type: string
operator:
anyOf:
- type: string
- type: 'null'
default: null
description: Single condition operator (shorthand).
title: Operator
platforms:
anyOf:
- items:
type: string
type: array
- type: 'null'
default: null
description: >-
Platforms to monitor: ['google_ads'], ['meta_ads'],
['google_ads', 'meta_ads'], etc. Default: all connected
platforms.
title: Platforms
scope_level:
anyOf:
- type: string
- type: 'null'
default: campaign
description: >-
What level to monitor: 'campaign' (default), 'ad_set'
(ad group level), or 'ad' (individual ad/creative
level).
title: Scope Level
threshold:
anyOf:
- type: number
- type: 'null'
default: null
description: Single condition threshold (shorthand).
title: Threshold
timeframe:
anyOf:
- type: string
- type: 'null'
default: null
description: Single condition timeframe (shorthand).
title: Timeframe
required:
- name
type: object
required:
- arguments
type: object
description: >-
All tool arguments are wrapped in an `arguments` object. The fields
accepted inside `arguments` are listed below — required fields are
marked with a red asterisk.
required: true
responses:
'200':
content:
application/json:
example:
data:
quota:
limit: 150
period_end: '2026-05-01'
tier: plus
used: 42
text: (tool-specific textual output for create_monitor)
success: true
tool: create_monitor
schema:
$ref: '#/components/schemas/SuccessResponse'
description: >-
Tool executed successfully. `data.text` carries the human-readable
result (markdown-friendly). `data.quota` shows your current usage
against the plan limit. `data.structured` appears when the tool
emits machine-parseable structured content. `data.content` appears
for tools that return non-text blocks (images, resources).
'400':
content:
application/json:
example:
error: >-
You have 25 meta_ads accounts connected. Please specify which
account to use by passing the ad_account_id parameter:
- Acme Holdings (ad_account_id="act_123456789")
- Acme EU (ad_account_id="act_987654321")
is_error: true
success: false
tool: create_monitor
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Tool-level error. The `error` string is safe to surface to end
users. Common causes: missing required argument, multi-account user
didn't specify which account, upstream platform validation failure.
'401':
content:
application/json:
example:
error: >-
Not authenticated. Please connect your ADSMCP account first
at https://adsmcp.si
is_error: true
success: false
tool: create_monitor
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid, expired, or revoked API key.
'402':
content:
application/json:
example:
error: |-
🚨 Monthly limit reached (150/150 tool calls on Plus tier).
Upgrade to Pro at https://adsmcp.si to keep building.
is_error: true
quota:
limit: 150
period_end: '2026-05-01'
tier: plus
upgrade_url: https://adsmcp.si
used: 150
success: false
tool: create_monitor
schema:
$ref: '#/components/schemas/QuotaErrorResponse'
description: >-
Quota exhausted for the current billing period. The response
includes a `quota` block with the current used/limit/tier values and
an `upgrade_url` to move up a tier.
'404':
content:
application/json:
example:
error: 'Tool not found: create_monitor'
is_error: true
success: false
tool: create_monitor
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unknown tool_name. Check /openapi.json for the full catalog.
'429':
content:
application/json:
example:
error: >-
Upstream platform rate limit hit (Meta Business Use Case
throttle at 95%). Retry after 60 seconds.
is_error: true
success: false
tool: create_monitor
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Rate-limited by the upstream ad platform (Meta, Google, LinkedIn,
TikTok). Retry with exponential backoff. Not the same as ADSMCP's
own quota — that returns 402.
'500':
content:
application/json:
example:
error: 'Internal error: RuntimeError'
is_error: true
success: false
tool: create_monitor
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Unexpected server error. Report to [email protected] with
request_id.
security:
- ApiKeyAuth: []
components:
schemas:
execute_create_monitor_MonitorConditionInput:
description: A single monitoring condition.
properties:
consecutive_days:
anyOf:
- type: integer
- type: 'null'
default: null
description: >-
Only trigger if condition is true for this many consecutive days.
E.g., 3 means 'true for 3 days in a row'. Min 1, max 30.
title: Consecutive Days
direction:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
For 'changes_by' operator: 'increase', 'decrease', or 'any'. E.g.,
'decrease' with threshold 30 means 'metric dropped by 30%'.
title: Direction
metric:
description: >-
Metric to check: 'roas', 'ctr', 'cpc', 'cpa', 'cpm', 'cpv', 'spend',
'conversions', 'impressions', 'clicks', 'cost_per_lead',
'conversion_rate', 'budget_utilization', 'video_views',
'engagement_rate'
title: Metric
type: string
operator:
description: >-
Comparison: 'less_than', 'greater_than', 'less_than_or_equal',
'greater_than_or_equal', 'changes_by'
title: Operator
type: string
threshold:
anyOf:
- type: number
- type: 'null'
default: null
description: >-
Threshold value for static comparisons (e.g., 2.0 for ROAS, 50 for
CPA). Required unless threshold_type is 'relative'.
title: Threshold
threshold_multiplier:
anyOf:
- type: number
- type: 'null'
default: null
description: >-
For relative thresholds: multiplier applied to baseline. E.g., 1.5
means '50% above baseline'. Required when threshold_type='relative'.
title: Threshold Multiplier
threshold_timeframe:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
For relative thresholds: timeframe for the baseline average. E.g.,
'last_30d' means compare to 30-day average. Default: 'last_30d'.
title: Threshold Timeframe
threshold_type:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
'static' (default) = compare to fixed threshold value. 'relative' =
compare to baseline metric × multiplier (e.g., 'CPA > 30-day average
× 1.5').
title: Threshold Type
timeframe:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Data window: 'last_24h', 'last_7d', 'last_14d', 'last_30d', 'today',
'yesterday', 'vs_previous_day'. If not specified, uses the lookback
period of available data.
title: Timeframe
required:
- metric
- operator
title: MonitorConditionInput
type: object
SuccessResponse:
description: >-
Returned on HTTP 200. `data.text` is the primary human-readable output.
`data.quota` is always present for billable calls. `data.structured` is
set only when the tool emits machine-parseable structured content.
`data.content` is set only when the tool emits non-text content blocks.
properties:
data:
properties:
content:
description: Non-text content blocks (images, resources).
items:
$ref: '#/components/schemas/ContentBlock'
type: array
quota:
$ref: '#/components/schemas/QuotaBlock'
structured:
additionalProperties: true
description: >-
Machine-parseable structured content when the tool provides it
(e.g. account selection prompts, widget payloads).
type: object
text:
description: >-
Human-readable output. Markdown-friendly for tools that emit
formatted lists, tables, or recommendations.
type: string
required:
- text
type: object
success:
const: true
type: boolean
tool:
description: Echoed tool_name from the request URL.
type: string
required:
- success
- data
- tool
type: object
ErrorResponse:
description: >-
Returned on HTTP 4xx / 5xx (except 402 which uses `QuotaErrorResponse`).
`error` is always a human-readable string safe to surface to end users.
properties:
error:
description: Human-readable error message.
type: string
is_error:
const: true
type: boolean
structured_content:
additionalProperties: true
description: >-
Present when the underlying tool attached structured metadata to the
error (e.g. account-selection lists).
type: object
success:
const: false
type: boolean
tool:
type: string
required:
- success
- error
- tool
type: object
QuotaErrorResponse:
description: >-
Returned on HTTP 402 when the monthly quota is exhausted. Identical to
`ErrorResponse` but with an additional `quota` block.
properties:
error:
type: string
is_error:
const: true
type: boolean
quota:
$ref: '#/components/schemas/QuotaBlock'
success:
const: false
type: boolean
tool:
type: string
required:
- success
- error
- tool
- quota
type: object
ContentBlock:
additionalProperties: true
description: >-
A non-text content block. Rare today; tools that attach images,
resources, or widget payloads populate `data.content` with blocks of
this shape.
properties:
type:
example: image
type: string
required:
- type
type: object
QuotaBlock:
description: >-
Current quota state for the API key owner. Attached to every successful
billable response under `data.quota`, and to 402 errors under `quota`
(plus `upgrade_url`).
properties:
limit:
description: Tool call allowance for the current tier.
example: 150
type: integer
period_end:
description: When the monthly counter resets (ISO date).
example: '2026-05-01'
format: date
type: string
tier:
description: Subscription tier of the account that owns the API key.
enum:
- free
- plus
- pro
- max
example: plus
type: string
upgrade_url:
description: Upgrade link (present only on 402 quota errors).
format: uri
type: string
used:
description: Tool calls consumed this billing period.
example: 42
type: integer
required:
- used
- limit
- tier
- period_end
type: object
securitySchemes:
ApiKeyAuth:
bearerFormat: API Key (sk_live_...)
description: >-
API key from https://adsmcp.si/dashboard/api-tokens. Prefix `sk_live_`. Treat as a
secret — never commit.
scheme: bearer
type: http