Labels

List campaign labels

media_planner.labels.list

Lists the labels used to tag the rows of media plans (name, hex color, order). In an account, the workspace's labels come first with inherited: true (they can be used on the account's campaigns but are managed from the workspace), then the account's own; include_inherited=false returns only the own ones. Use their ids in label_ids of media_planner.campaigns.create/update. Requires view access to the Media Planner.

Scope

media_planner:read

Permission

View the module

MCP tool

media_planner_labels_listOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.labels.list".

Declared cost: up to 402 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/labels" \
  -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/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a campaign label

media_planner.labels.create

Creates a campaign label with a name (up to 80 characters) and an optional hex color (#rrggbb; default a color of the palette), placed last. A workspace's labels are inherited by its accounts. Up to 200 per organization (409 limit_reached, details.resource campaign_labels). Returns the label with its id. Requires full access to the Media Planner.

Scope

media_planner:write

Permission

Edit in the module

MCP tool

media_planner_labels_createOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.labels.create".

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

Parameters

Response

Errors

Example

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

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 POST "https://api.mb-suite.com/v1/media-planner/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Rename or recolor a campaign label

media_planner.labels.update

Updates the name and/or the color (#rrggbb) of a campaign label of this organization, sent inside updates ({ label_id, updates: { name, color } }); the rows that use it keep it. An inherited label is 404 here: update it from the workspace. Returns the updated label. Requires full access to the Media Planner.

Scope

media_planner:write

Permission

Edit in the module

MCP tool

media_planner_labels_updateOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.labels.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/labels/{label_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

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/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Reorder campaign labels

media_planner.labels.reorder

Sets the order of this organization's campaign labels: label_ids in the new order (position = index). All or nothing: an id that is not a label of this organization stops the whole reorder (404). Requires full access to the Media Planner.

Scope

media_planner:write

Permission

Edit in the module

MCP tool

media_planner_labels_reorderOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.labels.reorder".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/media-planner/labels/reorder" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "label_ids": [
    "LABEL_ID"
  ]
}'

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 POST "https://api.mb-suite.com/v1/media-planner/labels/reorder" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "label_ids": [
    "LABEL_ID"
  ]
}'

Delete a campaign label

media_planner.labels.delete

Deletes a campaign label and removes it from every row that has it, in this organization and, for a workspace label, in the accounts the person can reach. The label goes to the 30-day trash; restoring it brings the label back and puts it back on those rows (the ones that still exist; the trash keeps up to 5,000 of them, and with more the trash item says linked_truncated and the dry run warns). The dry run says how many rows have it. Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete. Returns how many rows were updated. Requires full access to the Media Planner.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

media_planner:write and “Allow deletions” (media_planner:delete in OAuth)

Permission

Edit in the module

MCP tool

media_planner_labels_deleteOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.labels.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/media-planner/labels/{label_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 -X DELETE "https://api.mb-suite.com/v1/media-planner/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"