Does updating context hints append to the existing list?

Definition: No. In OpenAI Ads, sending context_hints in an ad-group update replaces the current list. To add one hint, retrieve the existing list, append the new value locally, and submit the complete intended list.

Key facts

• OpenAI defines context hints as additional information about the ads in an ad group. The targeting documentation says they can describe relevant products, use cases, or needs that the creative and landing page may not fully cover.
• The same documentation says hints are not exact-match keywords and do not replace explicit geographic, platform, or audience targeting.
• OpenAI's Ad Groups API reference types context_hints as an optional string[] field and describes the values as free-form audience or placement hints.
• An ad group can contain up to 2,000 hints. The targeting page says the limit does not need to be filled.
• The documented update endpoint is POST /ad_groups/{ad_group_id}. All fields are optional on an ad-group update.

What happens when context_hints is sent?

The targeting documentation states the replacement rule directly: updating context_hints replaces the current list. The field is therefore a complete-list field for this operation. A request containing one new value does not mean “add this value” to the server-side list.

OpenAI shows this request for setting the list on an ad group:

curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_123" \
  -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "context_hints": [
      "Lightweight trail running shoes for rocky terrain",
      "Water-resistant footwear for wet-weather hiking"
    ]
  }'

The array in that request is the list saved by the update. The documentation also states that an ad group may contain up to 2,000 hints.

How do you add one hint?

Use a read-modify-write sequence. First retrieve the ad group and read its current context_hints array. Add the new value to that local list, then send the full list in the context_hints field to POST /v1/ad_groups/{ad_group_id}.

The reference describes context_hints as an optional field on update, while the targeting page specifies that the values replace the current list. A caller that wants to preserve existing hints must include them again in the submitted array.

Can you clear the list or leave it unchanged?

Send an empty array to clear the context-hint list. Omit context_hints when the update should leave that list unchanged. These are different requests: "context_hints": [] expresses an empty saved list, while a request with no context_hints field does not update the field.

Hints also have a defined scope. OpenAI describes them as information about when an ad may be useful, and says they help guide ad matching. Geographic, platform, and audience restrictions remain campaign targeting settings, so a context-hint update does not substitute for those settings.

How can you verify the saved list?

Retrieve the ad group after the update and inspect the returned context_hints array. OpenAI's example response includes the field alongside the ad-group id, timestamps, name, description, status, and bidding configuration. This read-back shows which complete list the API stored.

Related terms

• Ads in ChatGPT
• OAI-AdsBot
• ChatGPT utm_source parameter

FAQ

Does posting one new hint append it?

No. The targeting documentation says that updating context_hints replaces the current list. Retrieve the existing array and include the new value in the complete replacement list.

What happens when context_hints is omitted?

The field stays unchanged when it is omitted. OpenAI documents omission as the way to leave the list unchanged during an update.

What request clears all hints?

Send "context_hints": [] in the ad-group update. OpenAI documents an empty array as the clear operation.

Are context hints geographic targeting?

No. OpenAI describes hints as additional ad information and separately says they do not replace geographic, platform, or audience targeting.

Sources

1. OpenAI Developers, "Targeting", undated
2. OpenAI Developers, "Ad Groups", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer