GaiaAds API Reference v2.1

Welcome to the GaiaAds Developer Documentation. Our REST API empowers you to manage programmatic advertising campaigns at scale. Monitor performance, automate bid adjustments, and sync creative assets programmatically.

Base URL: https://api.gaiaads.com/v2

Authentication

The GaiaAds API uses Bearer Token authentication. You must include your API key in the Authorization header for all requests.

curl -X GET https://api.gaiaads.com/v2/campaigns \ -H "Authorization: Bearer ga_live_83749283749283" \ -H "Content-Type: application/json"

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Pagination

All list API responses are paginated. We use cursor-based pagination via the page parameter.

{ "data": [...], "meta": { "total": 145, "page": 2, "limit": 20, "has_more": true } }

Errors

GaiaAds uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Description
200 OK - Request succeeded
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong on our end
GET

/campaigns

Returns a paginated list of campaigns belonging to your account.

Query Parameters

Parameter Type Description
limit integer Number of results to return per page. Max 100. Default 20.
status string Filter by status: ACTIVE, PAUSED, ARCHIVED.
sort string Field to sort by, e.g. -created_at.

Response Example

{ "data": [ { "id": "cmp_839201", "name": "Q1 Brand Awareness", "status": "ACTIVE", "budget_daily": 50000, "bid_strategy": { "type": "TARGET_CPA", "value": 250 }, "created_at": "2026-01-15T10:30:00Z" } ], "meta": { "total": 14, "page": 1, "has_more": false } }
POST

/campaigns

Create a new campaign. Campaigns are created in PAUSED state by default.

Body Parameters

Field Type Description
name string Required. Unique name for the campaign.
objective string One of BRAND_AWARENESS, TRAFFIC, CONVERSIONS.
budget_daily integer Daily budget cap in micros (e.g. $10.00 = 1000000).
{ "name": "Summer Sale 2026", "objective": "CONVERSIONS", "budget_daily": 10000000, "start_date": "2026-06-01" }
GET

/campaigns/:id

Retrieve a specific campaign by its ID.

GET /campaigns/cmp_839201
PUT

/campaigns/:id

Update campaign settings. Only provided fields are updated.

{ "status": "ACTIVE", "budget_daily": 75000 }
GET

/reports/daily

Get pre-aggregated daily stats for your account.

GET /reports/daily?date=2026-01-20
POST

/reports/custom

Generate a synchronous or asynchronous report based on provided metrics and dimensions.

POST /reports/custom { "date_range": "LAST_30_DAYS", "dimensions": ["campaign_id", "device_os"], "metrics": ["impressions", "clicks", "spend", "conversions"], "filters": [ { "field": "campaign_id", "operator": "IN", "value": ["cmp_839201", "cmp_992102"] } ] }

Creative Types (Enum)

  • BANNER - Standard display banner (JPG, PNG)
  • VIDEO - VAST video tag
  • NATIVE - Native ad assets (Title, Icon, Image, Desc)
  • AUDIO - Audio ad (MP3)

Geo Codes

We use ISO 3166-1 alpha-2 country codes (e.g. US, GB, DE) and a proprietary city ID map available for download via the dashboard.