[[campaigns.ad_groups.ads]] entries, nested within the ad group they belong to. A responsive search ad (RSA) is built from a pool of headlines and descriptions — you supply up to 15 headlines and up to 4 descriptions, and Google automatically tests combinations to find the best-performing assembly for each auction. Keeping your creative config clean and well-named makes it easy for both humans and AI agents to identify, edit, and test ads without accidentally modifying the wrong creative.
Full Example
[[campaigns.ad_groups.ads]]
Each entry in the ads array represents a single ad within the parent ad group.
A descriptive internal name for this ad. The name is not shown to users — it exists so that you and your AI agent can reference this specific ad unambiguously in instructions and diffs.Use names that reflect the ad’s creative angle or test hypothesis rather than a generic label:
| ✅ Descriptive | ❌ Generic |
|---|---|
"Just-in-Time DB Access" | "Ad 1" |
"Approvals Angle — Q2 Test" | "RSA June" |
Whether the ad is eligible to serve.
| Value | Behaviour |
|---|---|
"ENABLED" | Ad is live and eligible to serve |
"PAUSED" | Ad is suspended but retained |
The ad format. Currently supported value:
| Value | Description |
|---|---|
"RESPONSIVE_SEARCH_AD" | A responsive search ad with multiple headlines and descriptions that Google assembles automatically |
The landing page URL(s) for this ad. The first URL in the array is used as the primary destination. Include UTM parameters directly in the URL to track click sources.
Optional display-URL path segment — the first part of the
example.com/path1/path2 suffix shown in the rendered ad. Maximum 15 characters. It is cosmetic and independent of final_urls.Optional second display-URL path segment. Maximum 15 characters. Only meaningful when
path1 is also set.[[campaigns.ad_groups.ads.headlines]]
Headlines are the most prominent part of a search ad. Google selects up to three headlines per impression and assembles them into the ad title.
The headline text. Maximum 30 characters (including spaces). Headlines must make sense when shown alongside any other headline in the same pool, in any order.Limits: Minimum 3 headlines required. Maximum 15 headlines per RSA. Google recommends at least 8–10 for meaningful optimisation.Tips:
- Include your primary keyword in at least one headline
- Vary the angle: feature, benefit, social proof, call to action
- Avoid repeating the same phrase across multiple headlines
Optional. Locks this headline to a fixed position instead of letting Google place it freely. 1-based, valid values Pinning reduces the combinations Google can test, so pin sparingly — typically only a brand or legal headline that must always appear in position 1.
1–3 (HEADLINE_1, HEADLINE_2, HEADLINE_3). Omit to leave the headline unpinned. Multiple headlines may share a pin — Google rotates among them in that slot.[[campaigns.ad_groups.ads.descriptions]]
Descriptions appear below the headline row and provide supporting detail about the offer. Google selects up to two descriptions per impression.
The description text. Maximum 90 characters (including spaces).Limits: Minimum 2 descriptions required. Maximum 4 descriptions per RSA.Tips:
- Each description should stand alone — Google may show any single description with any pair of headlines
- End with a clear call to action where possible
- Use the full character allowance; longer descriptions tend to perform better
Optional. Locks this description to a fixed position. 1-based, valid values
1–2 (DESCRIPTION_1, DESCRIPTION_2). Omit to leave it unpinned. Multiple descriptions may share a pin.How Google Assembles RSA Combinations
When you add multiple headlines and descriptions, Google’s system automatically tests different combinations to learn which assemblies drive the best click-through and conversion rates for each query and audience. You do not control which combination shows in any given auction. This means every headline and description you write must:- Make grammatical sense when combined with any other asset in the pool
- Not repeat content already covered by another asset in the same pool
- Deliver value independently — do not split a single sentence across two assets
Naming Conventions for Agent Usability
Because AI agents reference ads by name when making edits, ambiguous names cause errors. Follow these conventions:- Include the creative angle:
"Price Anchor Variant","Feature-Led RSA","Competitor Comparison" - Include a date or test label for experiments:
"Free Trial Offer — 2026-Q2" - Avoid names like
"Ad 1","RSA","Main Ad"— these are meaningless when an account has hundreds of ads
Related Pages
- Campaigns — campaign-level settings, budgets, and targeting
- Keywords — keywords and negatives that live alongside ads inside ad groups
- Account Root — how campaign files (and the ad groups inside them) are imported