Dimensions and labels

Overview

A dimension is an account’s named organizing axis, such as Market, Quarter, or Brand. A label is one value from that dimension attached to an advertiser, campaign, creative, or creative asset in a Buyer Account, or to Library Material in a Seller Account. Dimensions make labels consistent across their applicable objects: the same value means the same thing everywhere in the account. Every Buyer Account also has the built-in tags dimension. It is open, so you can apply a new tag value without creating it first. There is no separate tag object or tag tool. Dimensions organize work; they do not grant authority, select inventory, change targeting, or cross an AdCP boundary. Dimensions do not have their own screen. They appear as object labels, search filters, buyer campaign-delivery report axes, and as one Dimensions multi-select on the Advertisers and Campaigns Pages. Its values include the dimension name, such as Market › US, and the control reads how many you have selected. Each labeled row still shows its own labels as chips. The Pages are for reading and filtering: open one campaign to edit its labels from the Labels section when permitted. Ask your agent to create dimensions or to label many campaigns or advertisers at once.

Dimension fields

Field	Type	Notes
`id`	string	Opaque server-issued identifier. Use it to read or update the dimension.
`key`	string	Immutable owner-chosen slug, unique in the account. It is the `dimension` of a label entry in `labels` and `filter.labels`.
`name`	string	Display name. Rename this without changing `key`.
`valuesMode`	`open` or `governed`	Open dimensions accept a new normalized value when you apply a label. Governed dimensions accept only their listed active values.
`values`	array	Each value has a stable `value`, display `name`, and `retired` state. Retired values stay in history but cannot be newly applied.
`appliesTo`	array	Buyer dimensions may label any of `advertiser`, `campaign`, `creative`, and `creative_asset`. Seller dimensions may label only `material`.
`usage`	object	Read-only counts of labeled objects for each kind: advertisers, campaigns, creatives, creative assets, and Material.
`retired`	boolean	Retired dimensions cannot receive new labels but remain readable.

Create and manage dimensions

On the V3 MCP endpoint, use save_dimension to create a dimension with a unique key, display name, value mode, applicable object kinds, and an idempotency key. After creation, use its returned id for updates; key is immutable. The same tool can add or rename values, merge a value into another value, or retire a value or the whole dimension. mergeInto must name an existing active target value. Merging moves existing labels to that target but does not retire the source: retire a merged source explicitly when it should no longer be available. Buyer Accounts can have at most 20 dimensions; Seller Accounts can have at most 20 seller-created dimensions. A dimension has at most 200 values, and an object has at most 50 labels. The built-in tags dimension counts toward a Buyer’s 20-dimension limit and always remains open. Seller dimensions are available when the Library is available for your storefront and can apply only to Material. Category, Topic, Audience, and Vertical are system-owned, cap-exempt Material facets; sellers cannot create or edit them. The daily seller Library seed reconciles those facets from Material metadata and removes labels that metadata no longer supports. In chat, ask to apply labels in bulk. The agent uses save_dimension and save_campaign or save_advertiser as appropriate. Only the first-party host re-reads an open Campaigns Page when the Page’s data changes. Other chat clients do not re-read, and Advertisers has no refresh path or advertiser label drill-in, so advertiser label changes are made in chat.

Built-in tags

Buyers can use the built-in tags dimension as one of their 20 account dimensions.

Apply and find labels

Pass labels to save_advertiser, save_campaign, save_creative, upload_creative_asset, or seller save_material:

{
  "labels": [
    { "dimension": "market", "values": ["us", "canada"] },
    { "dimension": "tags", "values": ["launch"] }
  ]
}

labels is a list of entries, one per dimension, each with the dimension’s key as dimension and the value slugs as values. Each supplied dimension replaces that dimension’s labels on the object; pass an empty values list to clear that dimension. A dimension may appear once in the list. Omitting labels leaves labels unchanged. get and search return the current labels as the same list of { "dimension", "values" } entries, so you can read an object, change one entry and send the list back.

Earlier versions took labels as a map, { "market": ["us", "canada"] }. The map form still works for now and means the same as the list, but it is deprecated and will be removed. Send the list.

Use search with kind: "advertiser", kind: "campaign", kind: "creative", kind: "creative_asset", or seller kind: "material" and filter.labels, a list of { "dimension", "values" } entries. The filter is AND across entries and OR within an entry’s values. Send "values": ["unlabeled"] on its own to find objects with no active value for that dimension:

{
  "kind": "campaign",
  "filter": {
    "labels": [
      { "dimension": "market", "values": ["us", "canada"] },
      { "dimension": "quarter", "values": ["unlabeled"] }
    ]
  }
}

Each entry needs at least one value, and a dimension may appear once. List dimensions with search({ "kind": "dimension" }), optionally using filter.appliesTo, then read one with get({ "kind": "dimension", "id": "…" }). You cannot narrow appliesTo while the dimension still has labels on an object kind being removed; clear or move those labels first.

Group delivery by a label

For V3 buyer campaign delivery, pass a label axis as "labels.<dimensionKey>" in get_delivery.dimensions:

{
  "report": "campaign_delivery",
  "dimensions": ["labels.market"],
  "range": { "startDate": "2026-08-01", "endDate": "2026-08-31" }
}

The report reads the current labels on both the campaign and its advertiser. Rows with no active value are returned in the "Unlabeled" bucket. Because labels are resolved when you query the report, a later relabeling reorganizes historical rows too. An unknown, retired, or inapplicable key is rejected with the account’s available dimensions. Label grouping applies to the stored campaign_delivery report. The additive live_campaign_delivery mode preserves one exact campaign’s provider response and does not accept grouping dimensions.

Advertiser

Advertiser ownership and fields

Campaign

Campaign ownership and fields

Start here

Buy media

Sell media

Help and updates

Dimensions and labels

Overview

Dimension fields

Create and manage dimensions

Built-in tags

Apply and find labels

Group delivery by a label

Advertiser

Campaign

​Overview

​Dimension fields

​Create and manage dimensions

​Built-in tags

​Apply and find labels

​Group delivery by a label

​Related

Advertiser

Campaign

Overview

Dimension fields

Create and manage dimensions

Built-in tags

Apply and find labels

Group delivery by a label

Related