Campaigns

A campaign is the top-level Ads API resource. It contains a lifetime budget, country targeting, an optional schedule, and one or more ad groups.

The campaign object

{
  "id": "cmpn_67f480125c61f3e66f163c22",
  "name": "Spring launch",
  "description": "Promote the new productivity bundle.",
  "status": "active",
  "bidding_type": "clicks",
  "budget": {
    "lifetime_spend_limit_micros": 25000000
  },
  "targeting": {
    "locations": {
      "include": ["US", "CA"]
    }
  },
  "start_time": null,
  "end_time": null,
  "created_at": 1744070418,
  "updated_at": 1744070418
}

Field	Type	Description
id	string	Campaign ID, prefixed with cmpn_.
name	string	Internal campaign name.
description	string or null	Optional campaign description.
status	string	active, paused, or archived.
bidding_type	string	Campaign objective. Elo supports clicks only.
budget.lifetime_spend_limit_micros	integer	Lifetime budget in millionths of a US dollar.
targeting.locations.include	string[]	Included ISO country codes. An empty list targets all countries.
start_time	integer or null	Start time as a Unix timestamp in seconds.
end_time	integer or null	End time as a Unix timestamp in seconds.
created_at	integer	Creation time as a Unix timestamp in seconds.
updated_at	integer	Last update time as a Unix timestamp in seconds.

Create a campaign

POST /campaigns

Field	Type	Required	Description
name	string	Yes	From 3 to 1,000 characters.
budget	object	Yes	The complete budget object.
budget.lifetime_spend_limit_micros	integer	Yes	At least 1000000.
description	string	No	Campaign description.
bidding_type	string	No	Only clicks is supported. Defaults to clicks.
targeting	object	No	Country targeting. Defaults to all countries.
targeting.locations.include	string[]	No	ISO 3166-1 alpha-2 country codes.
status	string	No	active or paused. Defaults to active.
start_time	integer	No	Start time as a Unix timestamp in seconds.
end_time	integer	No	End time as a Unix timestamp in seconds and after start_time.

Country codes are normalized to uppercase.

curl -X POST "https://api.withgrowl.com/v1/adm/campaigns" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring launch",
    "description": "Promote the new productivity bundle.",
    "status": "paused",
    "bidding_type": "clicks",
    "budget": {
      "lifetime_spend_limit_micros": 25000000
    },
    "targeting": {
      "locations": {
        "include": ["US", "CA"]
      }
    }
  }'

List campaigns

GET /campaigns

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

curl "https://api.withgrowl.com/v1/adm/campaigns?limit=20&order=desc" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "cmpn_67f480125c61f3e66f163c22",
      "name": "Spring launch",
      "description": "Promote the new productivity bundle.",
      "status": "paused",
      "bidding_type": "clicks",
      "budget": {
        "lifetime_spend_limit_micros": 25000000
      },
      "targeting": {
        "locations": {
          "include": ["US", "CA"]
        }
      },
      "start_time": null,
      "end_time": null,
      "created_at": 1744070418,
      "updated_at": 1744070418
    }
  ],
  "has_more": false,
  "first_id": "cmpn_67f480125c61f3e66f163c22",
  "last_id": "cmpn_67f480125c61f3e66f163c22"
}

Retrieve a campaign

GET /campaigns/{campaign_id}

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

Update a campaign

POST /campaigns/{campaign_id}

You can update name, description, budget, targeting, start_time, and end_time. Send the complete budget or targeting object when changing it. Set description, start_time, or end_time to null to clear it.

You cannot update bidding_type after creation.

Use a state action instead of including status in an update.

curl -X POST "https://api.withgrowl.com/v1/adm/campaigns/cmpn_67f480125c61f3e66f163c22" \
  -H "Authorization: Bearer $ELO_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated launch campaign.",
    "budget": {
      "lifetime_spend_limit_micros": 30000000
    }
  }'

Change campaign state

Each endpoint returns the updated campaign object.

• POST /campaigns/{campaign_id}/activate
• POST /campaigns/{campaign_id}/pause
• POST /campaigns/{campaign_id}/archive

curl -X POST "https://api.withgrowl.com/v1/adm/campaigns/cmpn_67f480125c61f3e66f163c22/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 campaign return 422.