Skip to main content
The GET /v1/campaigns endpoint returns campaigns from all connected platforms in a unified format. You can filter by platform, status, and paginate through results using cursors.

​
Basic Request

curl -X GET "https://api.adrelay.dev/v1/campaigns" \
  -H "X-API-Key: $ADRELAY_API_KEY"

​
Query Parameters

ParameterTypeDefaultDescription
platformstringallFilter by platform: google_ads, meta_ads, tiktok_ads
statusstringallFilter by status: ACTIVE, PAUSED, REMOVED, ENDED
limitinteger25Number of results per page (max 100)
cursorstring—Cursor for the next page of results

​
Filtering by Platform

Fetch only Google Ads campaigns: 
curl -X GET "https://api.adrelay.dev/v1/campaigns?platform=google_ads" \
  -H "X-API-Key: $ADRELAY_API_KEY"

​
Filtering by Status

Fetch only active campaigns across all platforms: 
curl -X GET "https://api.adrelay.dev/v1/campaigns?status=ACTIVE" \
  -H "X-API-Key: $ADRELAY_API_KEY"
Combine filters: 
curl -X GET "https://api.adrelay.dev/v1/campaigns?platform=meta_ads&status=PAUSED" \
  -H "X-API-Key: $ADRELAY_API_KEY"

​
Cursor Pagination

AdRelay uses cursor-based pagination. Each response includes a pagination object indicating whether more results are available and providing a cursor for the next page.

​
Response Shape

{
  "unified": [
    {
      "id": "camp_abc123",
      "platform": "google_ads",
      "remote_id": "123456789",
      "name": "Summer Sale 2026",
      "status": "ACTIVE",
      "goal": "CONVERSIONS",
      "budget_amount": 50.00,
      "budget_period": "DAILY",
      "currency": "USD",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-15T08:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImNhbXBfYWJjMTIzIn0=",
    "has_more": true
  }
}

​
Paginating Through Results

To fetch the next page, pass the next_cursor value as the cursor query parameter: 
curl -X GET "https://api.adrelay.dev/v1/campaigns?cursor=eyJpZCI6ImNhbXBfYWJjMTIzIn0=" \
  -H "X-API-Key: $ADRELAY_API_KEY"
When has_more is false, you have reached the last page.

​
Full Pagination Example (Node.js)

async function getAllCampaigns() {
  const campaigns = [];
  let cursor = null;

  do {
    const url = new URL("https://api.adrelay.dev/v1/campaigns");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url.toString(), {
      headers: { "X-API-Key": process.env.ADRELAY_API_KEY },
    });

    const data = await response.json();
    campaigns.push(...data.unified);

    cursor = data.pagination.has_more ? data.pagination.next_cursor : null;
  } while (cursor);

  return campaigns;
}

​
Campaign Object Fields

FieldTypeDescription
idstringAdRelay’s unique identifier for the campaign
platformstringSource platform (google_ads, meta_ads, tiktok_ads)
remote_idstringThe campaign ID on the original platform
namestringCampaign name
statusstringACTIVE, PAUSED, REMOVED, or ENDED
goalstringCampaign objective (e.g., CONVERSIONS, AWARENESS, TRAFFIC)
budget_amountnumberBudget amount in the campaign’s currency
budget_periodstringDAILY or LIFETIME
currencystringISO 4217 currency code
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp