Automations

Get the workspace's media plan automations

media_planner.automation.get

Returns the workspace's media plan automations, which run over the plans of all its accounts: auto_sync (sync the costs daily or weekly at hour in timezone; day_of_week 0 = Sunday for weekly) and auto_archive (archive the finished plans delay_days after they end: 1, 3, 7, 14 or 30). Everything is off until someone turns it on. Only in the workspace (an account gets 400 workspace_only). Requires view access to the Media Planner.

Scope

media_planner:read

Permission

View the module

MCP tool

media_planner_automation_getOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.automation.get".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

No parameters.

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/automation" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/media-planner/automation" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Configure the workspace's media plan automations

media_planner.automation.update

Turns on, off or reconfigures the workspace's automations: auto_sync { enabled, frequency daily|weekly, hour 0-23, day_of_week 0-6 (weekly), timezone (IANA) } and auto_archive { enabled, delay_days 1|3|7|14|30 }. Only the fields sent change; unknown fields are rejected. Turning auto_sync on makes MB Suite read every account's linked campaigns from the ad platforms on schedule. Only owners and admins of the workspace (an account gets 400 workspace_only). Returns the resulting settings and changed (false when nothing changed: no write, no audit). Requires full access to the Media Planner.

Scope

media_planner:write

Permission

Edit in the module · Only owner, admin

MCP tool

media_planner_automation_updateOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.automation.update".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/media-planner/automation" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/media-planner/automation" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Run a media plan automation now

media_planner.automation.run

Starts, right now, one run of an automation over the plans of all the workspace's accounts, outside its schedule: auto_sync (syncs the costs of every plan with linked campaigns, reading Google Ads, Meta, TikTok and LinkedIn) or auto_archive (archives the plans that ended more than delay_days ago). It runs in the background on MB Suite's automation service and takes minutes: follow it with media_planner.automation.runs.get (run_id), or see the latest runs with media_planner.automation.runs.list. A second run of the same type while one is in progress is rejected (409 automation_run_in_progress). Accounts blocked for billing are skipped. Only owners and admins of the workspace. Requires full access to the Media Planner.

Scope

media_planner:write

Permission

Edit in the module · Only owner, admin

MCP tool

media_planner_automation_runOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.automation.run".

Declared cost: up to 1 reads and 2 writes per call (they count against the daily quota). Touches an external platform (cloud_run): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/media-planner/automation/run" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "type": "auto_sync"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

List the runs of the media plan automations

media_planner.automation.runs.list

Lists the workspace's automation runs, newest first, paginated by cursor (limit 50 by default, up to 200): type (auto_sync, auto_archive), trigger (cron or manual), status (pending, running, completed, failed), start, end and duration, who started a manual run (triggered_by and triggered_by_name), stats (accounts and plans processed, plans synced or archived, errors) and error_count. The per-plan results and the errors of one run are in media_planner.automation.runs.get. Only in the workspace. Requires view access to the Media Planner.

Scope

media_planner:read

Permission

View the module

MCP tool

media_planner_automation_runs_listOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.automation.runs.list".

Declared cost: up to 202 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/automation/runs" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/media-planner/automation/runs" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one run of the media plan automations

media_planner.automation.runs.get

Returns one automation run of the workspace (run_id from media_planner.automation.runs.list, or the one media_planner.automation.run returned) with what the list has (type, trigger, status, start, end, duration, who started it, stats, error_count) plus, per plan, the result (plan_results: account, plan, rows synced or rows that changed status, skipped when it had nothing to sync) and the errors by account and plan. While it is pending or running, plan_results and errors fill in as it goes. Not found: automation_run_not_found. Only in the workspace. Requires view access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).

Scope

media_planner:read

Permission

View the module

MCP tool

media_planner_automation_runs_getOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.automation.runs.get".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/automation/runs/{run_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/media-planner/automation/runs/{run_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"