Ads API

The Elo Ads API lets you create and manage an ad account’s campaigns, ad groups, and ads with JSON requests.

Base URL

Send requests to:

https://api.withgrowl.com/v1/adm

Authentication

Pass your Elo Ads API key as a bearer token on every request:

Authorization: Bearer $ELO_ADS_API_KEY

Each key is scoped to one ad account. Keep it on your server and never expose it in browser or mobile code. See Authentication for an example request.

Resources

Resource	Use for
Campaigns	Define a budget, country targeting, schedule, and state.
Ad groups	Configure click bidding and contextual hints within a campaign.
Ads	Manage the copy, destination, image, price, and state of a creative.
Insights	Query reporting scopes through the preview Insights contract.
Files	Use the preview upload contract for creative assets.

Ads belong to ad groups, and ad groups belong to campaigns:

Campaign
└── Ad group
    └── Ad

Start with the Quickstart to create the complete hierarchy. See Unsupported features before porting an existing OpenAI Ads API integration.

Request and response format

Most endpoints accept and return application/json. Create and update operations use POST; retrieve and list operations use GET.

Times in responses are Unix timestamps in seconds. USD amounts use micros, where 1,000,000 micros equals one US dollar.

Object states

Campaigns, ad groups, and ads can be active, paused, or archived. Use the dedicated action endpoints to change state. Archiving is permanent: an archived object cannot be updated, activated, or paused.

State changes do not cascade to child objects.

Pagination

Campaign, ad-group, and ad list endpoints use cursor pagination.

Parameter	Type	Default	Description
limit	integer	20	Number of objects to return, from 1 to 500.
after	string	—	Return objects after this ID.
before	string	—	Return objects before this ID.
order	string	desc	Return objects in asc or desc creation order.

Do not combine after and before. A list response has this shape:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "first_id": null,
  "last_id": null
}

Use last_id as after to request the next page, or first_id as before to request the previous page.

Errors

Errors use a consistent JSON envelope:

{
  "error": {
    "message": "Missing required parameter: 'budget'.",
    "type": "invalid_request_error",
    "param": "budget",
    "code": "missing_required_parameter"
  }
}

Common status codes are:

Status	Meaning
400	The request body or query parameters are invalid.
401	The API key is missing or invalid.
404	The object does not exist in the current ad account.
422	An image URL is invalid or an archived object cannot be changed.