Ad groups

An ad group belongs to one campaign. It contains a click bid, contextual hints, and one or more ads. Send billing_event_type: "click"; no other billing event type is accepted.

The ad-group object

{
  "id": "adgrp_67f480455c61f3e66f163c23",
  "campaign_id": "cmpn_67f480125c61f3e66f163c22",
  "name": "Productivity shoppers",
  "description": "People exploring productivity tools.",
  "status": "active",
  "bidding_config": {
    "billing_event_type": "click",
    "max_bid_micros": 250000
  },
  "context_hints": ["productivity", "team collaboration"],
  "created_at": 1744070469,
  "updated_at": 1744070469
}

Field	Type	Description
id	string	Ad-group ID, prefixed with adgrp_.
campaign_id	string	Parent campaign ID.
name	string	Internal ad-group name.
description	string or null	Optional ad-group description.
status	string	active, paused, or archived.
bidding_config.billing_event_type	string	click.
bidding_config.max_bid_micros	integer	Maximum bid for one click, in USD micros.
context_hints	string[]	Descriptions of contexts in which the ads are relevant.
created_at	integer	Creation time as a Unix timestamp in seconds.
updated_at	integer	Last update time as a Unix timestamp in seconds.

Create an ad group

POST /ad_groups

Field	Type	Required	Description
campaign_id	string	Yes	Parent campaign ID in the current ad account.
name	string	Yes	From 3 to 1,000 characters with at least one non-space character.
bidding_config	object	Yes	The complete bidding object.
bidding_config.billing_event_type	string	Yes	Elo recognizes click and impression, but rejects values other than click.
bidding_config.max_bid_micros	integer	Yes	From 1 to 100000000.
description	string	No	Ad-group description.
context_hints	string[]	No	Up to 25 hints, each from 1 to 100 characters.
status	string	Yes	active or paused.

max_bid_micros is the maximum bid for one click. For example, 250000 represents $0.25.

curl -X POST "https://api.withgrowl.com/v1/adm/ad_groups" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "cmpn_67f480125c61f3e66f163c22",
    "name": "Productivity shoppers",
    "description": "People exploring productivity tools.",
    "status": "paused",
    "context_hints": ["productivity", "team collaboration"],
    "bidding_config": {
      "billing_event_type": "click",
      "max_bid_micros": 250000
    }
  }'

List ad groups

GET /ad_groups

The endpoint supports the shared limit, after, before, and order pagination parameters. campaign_id is required.

curl "https://api.withgrowl.com/v1/adm/ad_groups?campaign_id=cmpn_67f480125c61f3e66f163c22&limit=20" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

Retrieve an ad group

GET /ad_groups/{ad_group_id}

curl "https://api.withgrowl.com/v1/adm/ad_groups/adgrp_67f480455c61f3e66f163c23" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

Update an ad group

POST /ad_groups/{ad_group_id}

You can update name, description, bidding_config, context_hints, and status. Send the complete bidding_config object when changing the bid. Set description to null to clear it. status accepts active, paused, or archived.

The parent campaign cannot be changed.

curl -X POST "https://api.withgrowl.com/v1/adm/ad_groups/adgrp_67f480455c61f3e66f163c23" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context_hints": ["productivity", "workflow automation"],
    "bidding_config": {
      "billing_event_type": "click",
      "max_bid_micros": 300000
    }
  }'

Change ad-group state

Each endpoint returns the updated ad-group object.

• POST /ad_groups/{ad_group_id}/activate
• POST /ad_groups/{ad_group_id}/pause
• POST /ad_groups/{ad_group_id}/archive

curl -X POST "https://api.withgrowl.com/v1/adm/ad_groups/adgrp_67f480455c61f3e66f163c23/activate" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

Archiving is permanent. Repeating the archive action succeeds, but other updates and state changes on an archived ad group return 422.