Lists the workspace's metric alerts, newest first, paginated by cursor (limit 50 by default, up to 200). Each alert watches one metric of a platform account connected to the workspace or to one of its Accounts (target_org_id) and is evaluated every hour; it comes with its condition, recipients, cooldown, whether it is on (enabled), its last evaluation (last_value, last_delta, consecutive_errors, last_error) and who created and last edited it (created_by_id, created_by_name, updated_by_id, updated_by_name). Optional filters target_org_id, platform and enabled: a filtered page is filled by reading further (up to 600 alerts per call), so it is short only when the filter is rare; keep following next_cursor while has_more is true. Alerts live in the workspace: called on an Account (its org_id) it lists that Account's own alerts, normally none. A key limited to some Accounts does not see the alerts that watch the others. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).
Escopo
alerts:read
Permissão
Ver o módulo
Tool do MCP
alerts_alerts_listNa superfície completa; na compacta, mb_execute_operation com id: "alerts.alerts.list".
Custo declarado: até 601 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
limitintegerqueryopcional
How many per page (default 50, at most 200).
Padrão: 50
cursorstringqueryopcional
The next_cursor of the previous page.
target_org_idstringqueryopcional
Only the alerts that watch this organization (the workspace or one of its Accounts).
Returns one alert: its condition (operator, threshold, threshold_type, period, comparison), the watched organization (target_org_id, target_org_name), the platform account (platform, account_id, account_name), the metric (metric, metric_label, metric_format), recipients (member ids with their emails, and external_emails), cooldown_hours, enabled, template_id, the evaluation state written by the hourly run (last_evaluated_at, last_triggered_at, last_value, last_delta, consecutive_errors, last_error, and disabled_reason when the system turned it off) and who created and last edited it (created_by_id, created_by_name, updated_by_id, updated_by_name). 404 alert_not_found when it does not exist in this workspace or watches an Account the credential does not reach. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).
Escopo
alerts:read
Permissão
Ver o módulo
Tool do MCP
alerts_alerts_getNa superfície completa; na compacta, mb_execute_operation com id: "alerts.alerts.get".
Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
alert_idstringrotaobrigatório
The alert id (alerts.alerts.list).
Resposta
idstring
Alert id.
namestring
Name.
target_org_idstring
The watched organization (the workspace or one of its Accounts).
platformstring
The platform.
account_idstring
The watched account on the platform.
metricstring
The metric id.
conditionobject
When it triggers.
recipientsarray<string>
Member ids that get the email and the in-app notice.
cooldown_hoursnumber
Hours it waits before notifying again.
enabledboolean
On: evaluated every hour.
created_atnumber
Created (epoch ms).
created_by_idstring | null
Uid of who created it.
created_by_namestring | null
Their name.
updated_atnumber
Last edited (epoch ms).
updated_by_idstring | null
Uid of who edited it last.
updated_by_namestring | null
Their name.
target_org_namestring | null
Its name.
account_namestring | null
Its name.
metric_labelstring | null
How the metric is shown.
metric_formatstring | null
currency, number or percent.
recipient_emailsarray<string>
Their emails, in the same order.
external_emailsarray<string>
Addresses outside the organization (email only).
disabled_reasonstring | null
Why the system turned it off: org_archived or auto_error (5 failed evaluations in a row).
template_idstring | null
The recommended template it comes from.
last_evaluated_atnumber | null
Last hourly evaluation (epoch ms).
last_triggered_atnumber | null
Last time it triggered (epoch ms).
last_valuenumber | null
The metric's value in the last evaluation.
last_deltanumber | null
Its change in the last evaluation, in percent.
consecutive_errorsnumber
Failed evaluations in a row (at 5 the system turns it off).
Creates a metric alert in the workspace. It watches metric of a platform account (platform + account_id, connected to the watched organization: see alerts.target_platforms.list) of the workspace itself or of one of its active Accounts (target_org_id, default the workspace). Every hour MB Suite compares the last complete period with the previous one (or the same period last year) and, when the condition holds, emails the recipients, notifies the members in the app and waits cooldown_hours before notifying again. condition: operator increased_by/decreased_by (a change, in percentage unless threshold_type is absolute) or above/below (the value itself; threshold_type is forced to absolute), threshold > 0, period 1d/7d/14d/30d (default 7d), comparison vs_previous_period (default) or vs_same_period_last_year. recipients: member ids from alerts.recipients.list (ids that cannot see the watched organization are dropped and returned in dropped_recipient_ids); external_emails: up to 10 addresses outside the organization (email only). At least one recipient is required. cooldown_hours: 6, 12, 24 (default), 48, 72 or 168. metric: an id from alerts.metrics.list (metric_label and metric_format default to the registry's). name defaults to one like 'CPC +20% Google Ads - Acme'; enabled defaults to true. Only owners and admins, on the workspace (its org_id; not on an Account). Errors: 404 external_account_not_linked (the account is not connected to the watched organization; details.platform says which platform); 400 invalid_metric, invalid_target, target_unavailable, recipients_required, workspace_required. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).
Instruções para agentes
Tell the person the alert is evaluated every hour and who will get the emails; mention any dropped_recipient_ids (they cannot see the watched account).
Escopo
alerts:write
Permissão
Editar no módulo · Só owner, admin
Tool do MCP
alerts_alerts_createNa superfície completa; na compacta, mb_execute_operation com id: "alerts.alerts.create".
The account on the platform, as alerts.target_platforms.list lists it (account_id).
metricstringcorpoobrigatório
The metric id, from alerts.metrics.list for that platform.
conditionobjectcorpoobrigatório
When it triggers.
namestringcorpoopcional
The alert's name (default: one like «CPC +20% Google Ads - Acme»).
target_org_idstringcorpoopcional
The watched organization: the workspace (default) or one of its active Accounts.
metric_labelstringcorpoopcional
How the metric is shown (default: the registry's label).
metric_formatenumcorpoopcional
currency, number or percent (default: the registry's).
Valores: currency, number, percent
recipientsarray<string>corpoopcional
Member ids from alerts.recipients.list (email and in-app notice); ids that cannot see the watched organization are dropped (dropped_recipient_ids). Up to 50.
external_emailsarray<string (email)>corpoopcional
Addresses outside the organization (for example the client's): email only. Up to 10.
cooldown_hoursenumcorpoopcional
Hours to wait before notifying again: 6, 12, 24 (default), 48, 72 or 168.
Valores: 6, 12, 24, 48, 72, 168
enabledbooleancorpoopcional
On (default true): evaluated every hour.
template_idstringcorpoopcional
The recommended template it comes from (alerts.metrics.list), if any.
Resposta
alert_idstring
The new alert's id.
alertobject
The alert as saved.
dropped_recipient_idsarray<string>
Recipient ids left out: they cannot see the watched organization or have no valid email.
Updates an alert: the fields to change go inside updates, next to alert_id (for example {alert_id, updates: {name, condition: {threshold}}}); sent at the top level they are rejected (400 unknown_field). The fields: name, target_org_id, platform, account_id, metric (with metric_label/metric_format), condition (only the fields sent change, the rest keep their value; above/below always use an absolute threshold), recipients (replaces the list; ids that cannot see the watched organization are dropped and returned in dropped_recipient_ids), external_emails (replaces the list), cooldown_hours, enabled (turning it on clears its errors) and template_id (null unlinks it). Changing the target, the platform or the account checks that the account is connected to the watched organization; changing the platform or the metric checks the metric exists for it. The trigger history is not touched. Values equal to the current ones change nothing (no write, no event). Unknown fields are rejected. Only owners and admins. Errors as in alerts.alerts.create (404 external_account_not_linked and the 400s); 404 alert_not_found. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).
Escopo
alerts:write
Permissão
Editar no módulo · Só owner, admin
Tool do MCP
alerts_alerts_updateNa superfície completa; na compacta, mb_execute_operation com id: "alerts.alerts.update".
Turns an alert on or off with enabled. Turning it on clears its consecutive errors and the reason the system turned it off (5 failed evaluations in a row, or its Account archived), so the next hourly evaluation starts clean; turning it off stops the evaluations and the emails until it is turned on again. Idempotent: asking for the state it already has changes nothing (changed: false). Only owners and admins; 404 alert_not_found. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).
Escopo
alerts:write
Permissão
Editar no módulo · Só owner, admin
Tool do MCP
alerts_alerts_toggleNa superfície completa; na compacta, mb_execute_operation com id: "alerts.alerts.toggle".
Deletes an alert: it stops being evaluated at once and goes to the 30-day trash, where an owner or admin can restore it as it was (platform.trash.restore). Its trigger history (alerts.history.list) is kept, because it records notifications that were already sent. Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete. Only owners and admins; 404 alert_not_found.
Com uma API key, este DELETE roda direto: o registro fica 30 dias na lixeira e a resposta traz o seu trash_item_id. Com um token OAuth, e pelo MCP, pede dry_run → confirm_token.
Escopo
alerts:writee «Permitir exclusões» (alerts:delete no OAuth)
Permissão
Editar no módulo · Só owner, admin
Tool do MCP
alerts_alerts_deleteNa superfície completa; na compacta, mb_execute_operation com id: "alerts.alerts.delete".
