Google Ad Manager Key-Values:
The Definitive Guide to Limits & API

Understanding the Types: Predefined vs Free-form

Google Ad Manager provides two types of targeting keys. The distinction affects how values are inserted via the API and how they surface in reports:

• Predefined: You must declare all possible values in the GAM console or via API beforehand. Typical example: gender=female,male,other. Best used when targeting values are static. These values map cleanly to reporting dimensions.
• Free-form: You define the key (e.g., search_term), but values are created dynamically when requests hit GAM from the browser tags. Typical example: keywords=running-shoes. Essential for high-cardinality dynamic data.

Critical Technical Limits You Must Know

The Google Ad Manager API throws blocking exceptions or silently truncates parameters if you violate these hard rules:

Recommended Key-Values by Inventory Type

To effectively target direct and programmatic ad campaigns, here are the essential key-values to configure based on your business model:

Simplifying Key-Values via the OrbiAds MCP Plugin

You no longer need to navigate the heavy GAM interface to configure targeting keys or values. The OrbiAds MCP plugin exposes direct writing tools for your AI agents or local scripts.

Step 1: Create the targeting key

# In Claude — OrbiAds MCP plugin
create_custom_targeting_key(
  name="pos",
  display_name="Position sur la page",
  key_type="PREDEFINED",
  reportable_type="ON",
  dry_run=false
)

Step 2: Add values to a predefined key:

# Append values to the targeting key (ID returned from Step 1)
create_custom_targeting_values(
  key_id="12984572",
  values=[
    {"name": "atf", "displayName": "Above the Fold"},
    {"name": "btf", "displayName": "Below the Fold"}
  ],
  dry_run=false
)

Visualizing with the Admin explorer tool

For logged-in users, OrbiAds provides a visual dashboard to inspect all active custom targeting keys and values at:

This explorer reads active configs dynamically, counts value instances, and displays predefined values in a tag list format to avoid spelling errors before launching campaigns.

Integration Code: From SOAP API to Client-side GPT

Here is how to create a targeting key programmatically using the Python SDK, and then implement targeting in the web browser using Google Publisher Tag (GPT).

1. Creating Key-Values in Python (SOAP SDK)

from googleads import ad_manager

# Initialiser le client Ad Manager
client = ad_manager.AdManagerClient.LoadFromStorage()
custom_targeting_service = client.GetService(
    'CustomTargetingService', version='v202602'
)

# Déclarer une clé de ciblage "freeform"
key = {
    'name': 'consent_status',
    'displayName': 'Consent status (GDPR)',
    'type': 'FREEFORM'
}

keys = custom_targeting_service.createCustomTargetingKeys([key])
print(f"Clé créée avec l'ID: {keys[0]['id']}")

2. Client-side targeting (JavaScript GPT)

Once configured on the server, append targeting coordinates inside the page headers:

window.googletag = window.googletag || { cmd: [] };
window.googletag.cmd.push(function () {
  // Ciblage au niveau de la page entière
  window.googletag.pubads().setTargeting('section', 'tech');
  window.googletag.pubads().setTargeting('consent', '1');

  // Ciblage spécifique sur un slot publicitaire particulier
  window.googletag.defineSlot('/1234/site/banner', [300, 250], 'div-gpt-ad')
    .setTargeting('pos', 'atf')
    .addService(window.googletag.pubads());
});

Robustness Best Practices

• Lowercasing in GPT: GPT automatically converts targeted values to lowercase in ad requests. Avoid injecting uppercase strings through the API to prevent targeting match failures.
• API Throttling: Modifying large volumes of targeting values over SOAP triggers QuotaError.EXCEEDED_QUOTA exceptions. Implement client-side exponential backoff of at least 500ms between batch requests.

Frequently asked questions about GAM Key-Values

What is the character limit for Google Ad Manager key-values?

Both the key name and each value are limited to 40 characters. Values are case-insensitive (Val equals val), and characters such as quotes, =, !, +, #, *, ~, ;, ^, parentheses, brackets, spaces and commas are not allowed.

How many custom targeting expressions can a line item have?

A line item supports up to 20 custom targeting expressions. A single SOAP API call can create up to 200 values per key; beyond that you must batch the requests.

What is the difference between predefined and free-form key-values?

Predefined keys require declaring all values in advance and map cleanly to reporting dimensions; free-form keys let values be created dynamically when the ad tag sends them from the browser, which suits high-cardinality or dynamic data.

How long does a new GAM key-value take to become active?

Allow 15 to 30 minutes of propagation latency after creating or modifying a key-value before it is active in live ad serving.

Can I create GAM key-values from an AI agent or script?

Yes. With the OrbiAds MCP server, an AI agent can call create_custom_targeting_key to declare a key and create_custom_targeting_values to add values, instead of using the GAM console.

Start Automating Your Targeting Structures

Leverage the OrbiAds MCP plugin to inspect and populate targeting parameters in seconds. Synchronize all your advertising properties with a few instructions.