> ## 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.

# Multi-Platform Campaigns

> Create campaigns across multiple ad platforms in a single API call.

AdRelay supports creating the same campaign across multiple platforms simultaneously using the `targets` array. This is useful when you want to launch a campaign across Google, Meta, and TikTok at the same time with consistent settings.

## Using the `targets` Array

Instead of specifying a single `platform`, provide a `targets` array listing the platforms you want to create the campaign on:

```bash 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": "Black Friday 2026",
    "goal": "SALES",
    "budget_amount": 100.00,
    "budget_period": "DAILY",
    "targets": ["google_ads", "meta_ads", "tiktok_ads"]
  }'
```

## Response Format

When using `targets`, the response includes results for each platform and a summary:

```json theme={null}
{
  "results": [
    {
      "platform": "google_ads",
      "status": "success",
      "campaign": {
        "id": "camp_ggl001",
        "platform": "google_ads",
        "remote_id": "111222333",
        "name": "Black Friday 2026",
        "status": "PAUSED",
        "goal": "SALES",
        "budget_amount": 100.00,
        "budget_period": "DAILY",
        "currency": "USD",
        "created_at": "2026-03-21T10:00:00Z",
        "updated_at": "2026-03-21T10:00:00Z"
      }
    },
    {
      "platform": "meta_ads",
      "status": "success",
      "campaign": {
        "id": "camp_meta002",
        "platform": "meta_ads",
        "remote_id": "444555666",
        "name": "Black Friday 2026",
        "status": "PAUSED",
        "goal": "SALES",
        "budget_amount": 100.00,
        "budget_period": "DAILY",
        "currency": "USD",
        "created_at": "2026-03-21T10:00:01Z",
        "updated_at": "2026-03-21T10:00:01Z"
      }
    },
    {
      "platform": "tiktok_ads",
      "status": "error",
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Minimum daily budget for TikTok Ads is $20.00. Received $100.00 which is valid, but account connection has expired.",
        "details": null
      }
    }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}
```

## Mixed Results Handling

Multi-platform creation uses a **best-effort** approach. If one platform fails, the others still succeed. This means you need to handle partial success:

```javascript 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: "Q2 Launch",
    goal: "TRAFFIC",
    budget_amount: 75.0,
    budget_period: "DAILY",
    targets: ["google_ads", "meta_ads"],
  }),
});

const data = await response.json();

// Check the summary
if (data.summary.failed > 0) {
  const failures = data.results.filter((r) => r.status === "error");
  for (const failure of failures) {
    console.error(`Failed on ${failure.platform}: ${failure.error.message}`);
  }
}

// Process successful campaigns
const campaigns = data.results
  .filter((r) => r.status === "success")
  .map((r) => r.campaign);
```

## The Summary Object

The `summary` object provides a quick overview of the multi-platform operation:

| Field       | Type    | Description                                                     |
| ----------- | ------- | --------------------------------------------------------------- |
| `total`     | integer | Total number of platforms targeted                              |
| `succeeded` | integer | Number of platforms where the campaign was created successfully |
| `failed`    | integer | Number of platforms where creation failed                       |

## HTTP Status Codes

| Scenario                              | Status Code        |
| ------------------------------------- | ------------------ |
| All platforms succeeded               | `201 Created`      |
| Some platforms succeeded, some failed | `207 Multi-Status` |
| All platforms failed                  | `400 Bad Request`  |

## Best Practices

* **Check connection status first** -- Call `GET /v1/connections` to verify all target platforms have `ACTIVE` connections before creating multi-platform campaigns.
* **Handle partial success** -- Always check the `summary` and iterate through `results` to handle failures gracefully.
* **Platform-specific budgets** -- Remember that TikTok Ads has a minimum daily budget of \$20. If your budget is below a platform's minimum, that platform will fail with a `VALIDATION_ERROR`.
* **Consistent naming** -- The same `name` is used across all platforms. Consider including a platform identifier in the name if you need to distinguish them on each platform's dashboard.