> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Dimensions and labels > Organize buyer objects and seller Library Material with 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 key 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`: ```json theme={null} { "labels": { "market": ["us", "canada"], "tags": ["launch"] } } ``` Each supplied dimension replaces that dimension's labels on the object; pass an empty array to clear that dimension. Omitting `labels` leaves labels unchanged. `get` and `search` return the current labels as the same `{ "dimensionKey": ["value"] }` shape. Use `search` with `kind: "advertiser"`, `kind: "campaign"`, `kind: "creative"`, `kind: "creative_asset"`, or seller `kind: "material"` and `filter.labels`. The filter is AND across dimension keys and OR within a value array. Use the literal `"unlabeled"` to find objects with no active value for one dimension: ```json theme={null} { "kind": "campaign", "filter": { "labels": { "market": ["us", "canada"], "quarter": "unlabeled" } } } ``` 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."` in `get_delivery.dimensions`: ```json theme={null} { "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. ## Related Advertiser ownership and fields Campaign ownership and fields This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.