Skip to main content
A dimension is a buyer account’s named organizing axis, such as Market, Quarter or Brand. A label is one value from a dimension attached to an advertiser or campaign. Dimensions keep labels consistent: the same value means the same thing everywhere in the account. Every buyer account also has the built-in tags dimension. It’s open, so you can apply a new tag without creating it first. There’s no separate tag object or tag tool. Dimensions organize work. They don’t grant access, select inventory, change targeting, or travel to sellers. They have no screen of their own: they show up as labels on objects, search filters and delivery report axes, and you set them up in chat or over MCP when you first organize work by an axis.

​
Dimension fields

​
Create and manage dimensions

Use save_dimension. Create with a unique key, a name, valuesMode, appliesTo and an idempotencyKey:
After that, update by id (the key can’t change). The same tool adds or renames values, retires a value (retired: true) or the whole dimension, and merges one value into another with mergeInto. mergeInto must name another existing, active value. Merging moves existing labels to the target but doesn’t retire the source; retire it explicitly when it should no longer be offered. You can’t narrow appliesTo while the dimension still labels objects of the kind you’re removing (“Clear or move them before narrowing appliesTo.”). List dimensions with search (kind: "dimension", optional filter.appliesTo) and read one with get (kind: "dimension", id).

​
Apply labels

Pass labels to save_advertiser or save_campaign:
  • Each dimension you send replaces that dimension’s labels on the object; [] clears it.
  • Omitting labels leaves every label unchanged.
  • Values are normalized: trimmed, lowercased, and spaces become dashes ("Q4 Launch" → q4-launch).
  • An open dimension learns a new value the first time you apply it. A governed dimension refuses values it doesn’t list, naming the allowed ones.
  • Unknown, retired or inapplicable dimensions and retired values are refused with the dimensions you can use.
get and search return labels in the same { "dimensionKey": ["value"] } shape. REST campaign and advertiser writes don’t take labels; use the MCP tools.

​
Find by label

search with kind: "advertiser" or kind: "campaign" takes filter.labels: AND across dimension keys, OR within a value array. The literal "unlabeled" finds objects with no value for a dimension.
Over REST, GET /api/v2/buyer/campaigns?labels= takes the same predicate as JSON, for example labels={"market":["us"],"quarter":"unlabeled"} (URL-encoded).

​
Group delivery by a label

In get_delivery (report: "campaign_delivery"), add a label axis as "labels.<key>":
Each row takes the campaign’s label for that dimension, or its advertiser’s when the campaign has none. Several values on one object read as one bucket joined with ”, ” (for example ca, us); rows with no value land in "Unlabeled". Labels are read when you run the report, so relabeling reorganizes past rows too. An unknown, retired or inapplicable key is refused with the available dimensions.

​
Who can use them

People in the buyer account can. Buyer agents can’t call save_dimension or read kind: "dimension", because dimensions are account-wide rather than per-advertiser.