GaiaAds API Reference v2.1

Company reference v2.1: endpoint addresses below are preserved from the supplied documentation. Confirm the working base URL, permissions, schema and limits with the account team before making requests. Examples are illustrative and contain no usable API credentials.

Money in examples: one currency unit = 1,000,000 micros, so USD 10 = 10,000,000 and USD 50 = 50,000,000. Confirm the actual API’s currency and field units; these examples do not verify a live contract. Request integration review.

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 ${GAIA_API_TOKEN}" \
-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. These examples use numbered pages via the page parameter. The invented example below shows page 2 of a five-record list, with two records per page. Confirm the production schema before implementing pagination.

{
"data": [{"id": "cmp_example_3"}, {"id": "cmp_example_4"}],
"meta": {
"total": 5,
"page": 2,
"limit": 2,
"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

page: illustrative 1-based page number; default 1. limit: results per page.

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": 50000000,
"bid_strategy": {
"type": "TARGET_CPA",
"value": 15000000
},
"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 = 10000000).

{
"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. Setting a campaign to ACTIVE may initiate paid delivery; use only the account-approved workflow. The example keeps it PAUSED.

{
"status": "PAUSED",
"budget_daily": 75000000
}

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.