> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrelay.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Campaigns

> Create ad campaigns programmatically through the AdRelay API.

Use the `POST /v1/campaigns` endpoint to create campaigns on any connected ad platform. AdRelay translates your request into the platform-specific format and creates the campaign on your behalf.

## Required Fields

| Field           | Type   | Description                                                                 |
| --------------- | ------ | --------------------------------------------------------------------------- |
| `name`          | string | Campaign name (max 255 characters)                                          |
| `goal`          | string | Campaign objective: `CONVERSIONS`, `AWARENESS`, `TRAFFIC`, `LEADS`, `SALES` |
| `budget_amount` | number | Budget amount in your account's currency                                    |
| `budget_period` | string | `DAILY` or `LIFETIME`                                                       |
| `platform`      | string | Target platform: `google_ads`, `meta_ads`, or `tiktok_ads`                  |

## Basic Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.adrelay.dev/v1/campaigns" \
    -H "X-API-Key: $ADRELAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Summer Sale 2026",
      "goal": "CONVERSIONS",
      "budget_amount": 50.00,
      "budget_period": "DAILY",
      "platform": "google_ads"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.adrelay.dev/v1/campaigns", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ADRELAY_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Summer Sale 2026",
      goal: "CONVERSIONS",
      budget_amount: 50.0,
      budget_period: "DAILY",
      platform: "google_ads",
    }),
  });

  const campaign = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.adrelay.dev/v1/campaigns",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json",
      },
      json={
          "name": "Summer Sale 2026",
          "goal": "CONVERSIONS",
          "budget_amount": 50.00,
          "budget_period": "DAILY",
          "platform": "google_ads",
      },
  )

  campaign = response.json()
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "camp_new789",
  "platform": "google_ads",
  "remote_id": "555666777",
  "name": "Summer Sale 2026",
  "status": "PAUSED",
  "goal": "CONVERSIONS",
  "budget_amount": 50.00,
  "budget_period": "DAILY",
  "currency": "USD",
  "created_at": "2026-03-21T10:00:00Z",
  "updated_at": "2026-03-21T10:00:00Z"
}
```

## Default Status

All campaigns are created with a status of `PAUSED` by default. This gives you the opportunity to review the campaign before it goes live. To activate a campaign, update its status:

```bash theme={null}
curl -X PATCH "https://api.adrelay.dev/v1/campaigns/camp_new789" \
  -H "X-API-Key: $ADRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "ACTIVE"}'
```

## Budget Handling

### Daily Budgets

The `budget_amount` with `budget_period: "DAILY"` sets the maximum spend per day. Each platform handles daily budgets slightly differently:

* **Google Ads** -- May spend up to 2x the daily budget on high-traffic days, but averages out over the month.
* **Meta Ads** -- May spend up to 25% more on high-opportunity days.
* **TikTok Ads** -- Strictly enforces the daily budget cap.

### Lifetime Budgets

Set `budget_period: "LIFETIME"` to specify a total budget for the campaign's duration. Note that lifetime budgets may require additional fields on some platforms.

## Platform Differences

While AdRelay normalizes the campaign creation interface, there are platform-specific behaviors to be aware of:

| Behavior              | Google Ads       | Meta Ads             | TikTok Ads           |
| --------------------- | ---------------- | -------------------- | -------------------- |
| Minimum daily budget  | \$1.00           | \$1.00               | \$20.00              |
| Budget currency       | Account currency | Account currency     | Account currency     |
| Campaign goal mapping | Direct           | Mapped to objectives | Mapped to objectives |
| Creation latency      | \~1-2s           | \~2-3s               | \~1-2s               |

<Info>
  AdRelay validates your request against platform-specific requirements before submitting. If a platform has a higher minimum budget, you will receive a validation error before the campaign is created.
</Info>

## Error Handling

Common creation errors:

| Code               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid fields. Check the `details` object for specifics. |
| `FORBIDDEN`        | No active connection for the specified platform.                     |
| `RATE_LIMITED`     | Too many requests. Retry after the `Retry-After` period.             |