API Integration Details | GaiaAds Knowledge Base

For advanced advertisers and agencies, the GaiaAds Management API offers programmatic control over campaigns, reporting, and assets. This guide complements the full API Reference.

1. Prerequisites

Before writing code, ensure you have:

API Access Enabled: Contact your account manager to enable API access. This is restricted to accounts with >$5k monthly spend.
API Key: Generate a Permanent Token in Settings > API Keys. Store this securely; it will not be shown again.
Environment: We provide a Sandbox environment at https://sandbox-api.gaiaads.com for testing without spending real money.

2. Authentication

All requests must include the Authorization header with your Bearer token.

                    Headers:
                    Authorization: Bearer ga_live_83749283749283
                    Content-Type: application/json
                    Accept: application/json
                

3. Python Implementation Example

Here is a robust Python script using `requests` to create a campaign and verify its status.

                    import requests
                    import json
                    import time

                    API_KEY = "ga_live_your_api_key"
                    BASE_URL = "https://api.gaiaads.com/v2"

                    headers = {
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json"
                    }

                    def create_campaign():
                    payload = {
                    "name": "API Automated Campaign Q1",
                    "objective": "CONVERSIONS",
                    "budget_daily": 5000000, # $50.00
                    "bid_strategy": {
                    "type": "TARGET_CPA",
                    "value": 1500000 # $15.00 CPA Goal
                    }
                    }

                    response = requests.post(f"{BASE_URL}/campaigns", json=payload, headers=headers)

                    if response.status_code == 201:
                    data = response.json()
                    print(f"Success! Campaign ID: {data['data']['id']}")
                    return data['data']['id']
                    else:
                    print(f"Error: {response.status_code} - {response.text}")
                    return None

                    if __name__ == "__main__":
                    campaign_id = create_campaign()
                

4. Rate Limiting

To ensure stability, we enforce rate limits on a per-account basis.

Read Requests (GET): 10 requests per second.
Write Requests (POST, PUT, DELETE): 2 requests per second.
Reporting API: 5 concurrent report jobs.

Handling 429s: If you receive a 429 Too Many Requests response, your application must respect the `Retry-After` header and back off exponentially.

5. Error Handling

We follow standard HTTP status codes.

400 Bad Request: Your JSON payload is malformed or missing required fields. Check the `errors` array in the response body for specific field validation messages.
401 Unauthorized: Your token is invalid, expired, or missing.
403 Forbidden: Your token is valid, but you do not have permission to access the requested resource (e.g., trying to access another account's campaign).
500 Internal Server Error: Something went wrong on our end. Please contact support with the X-Request-ID header value.

6. Webhooks

Instead of polling for status updates, register a webhook endpoint to receive real-time notifications for:

campaign.approved
creative.rejected
budget.exhausted