Ad Sets · CampaignKit API Docs

GET

/v1/meta/adsets

Listet Ad Sets, optional nach Ziel (target) und Status gefiltert. Die Antwort enthält das Ziel (target) statt einer Kampagnen-ID.

Query-Parameter

Name	Typ	Pflicht	Beschreibung
target	string	optional	Auf ein Ziel (Ziel-Schlüssel) filtern.
status	enum	optional	ACTIVE \| PAUSED \| ARCHIVED.
limit	integer	optional	Anzahl pro Seite (Default 25, max 100).
offset	integer	optional	Versatz für Pagination (Default 0).

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/meta/adsets`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77",
      "target": "sommerfest-2026",
      "name": "[CK] … · AdSet #1",
      "daily_budget_cents": 5000,
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "meta_adset_id": "604839271650"
    }
  ],
  "request_id": "…"
}

POST

/v1/meta/adsets

Legt ein Ad Set unter dem per `target` referenzierten Ziel an. Budget ist Pflicht (genau eines von daily_budget_cents oder lifetime_budget_cents) — das Ziel führt kein Budget, daher liegt es verbindlich auf dem Ad-Set. Der Name wird automatisch vergeben (Naming Convention). Optimierungsziel, Abrechnung, Platzierung (Plattformen/Positionen), Geo und promoted_object sind durch das Ziel gesperrt und werden serverseitig gesetzt.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
target	string	erforderlich	Ziel-Schlüssel des von uns eingerichteten Ziels. Bestimmt Optimierung, Platzierung, Geo, Pixel und DSA. Den Schlüssel erhältst du von uns. `z. B. sommerfest-2026`
daily_budget_cents	integer (Cent)	erforderlich	Tagesbudget in Cent (5000 = 50,00 € in Konto-Währung). Pflicht: genau eines von daily_budget_cents ODER lifetime_budget_cents muss gesetzt sein — das Ziel setzt kein Budget, daher liegt das Budget verbindlich auf dem Ad-Set. `z. B. 5000`
lifetime_budget_cents	integer (Cent)	erforderlich	Laufzeitbudget in Cent (50000 = 500,00 €). Pflicht: genau eines von daily_budget_cents ODER lifetime_budget_cents. Bei lifetime_budget_cents ist end_time zwingend erforderlich. `z. B. 50000`
start_time	string (ISO 8601)	optional	Startzeitpunkt. Default: sofort. `z. B. 2026-06-01T10:00:00+02:00`
end_time	string (ISO 8601)	optional	Endzeitpunkt. Bei lifetime_budget_cents Pflicht. `z. B. 2026-06-30T23:59:59+02:00`
targeting	object	optional	Optionale Zusatz-Zielgruppe. Nur die folgenden Unterfelder sind erlaubt — alles andere ist durch das Ziel gesperrt. `z. B. {"age_min":25,"age_max":45,"genders":[1,2]}`
targeting.age_min	integer	optional	Mindestalter. 13–65. `z. B. 25`
targeting.age_max	integer	optional	Höchstalter. 13–65 (65 = '65+'). `z. B. 45`
targeting.genders	integer[]	optional	1 = Männlich, 2 = Weiblich. Weggelassen = alle. `z. B. [1,2]`
targeting.flexible_spec	object[]	optional	Interessen-/Verhaltens-Targeting. Array von OR-Gruppen (untereinander AND-verknüpft), je mit interests/behaviors/life_events als [{id,name}]. IDs kommen aus dem Interessen-Lookup. `z. B. [{"interests":[{"id":"6003139266461","name":"Live music"}]}]`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/meta/adsets`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      target: "sommerfest-2026",
      daily_budget_cents: 5000,
      lifetime_budget_cents: 50000,
      start_time: 2026-06-01T10:00:00+02:00,
      end_time: 2026-06-30T23:59:59+02:00,
      targeting: {"age_min":25,"age_max":45,"genders":[1,2]},
      targeting.age_min: 25,
      targeting.age_max: 45,
      targeting.genders: [1,2],
      targeting.flexible_spec: [{"interests":[{"id":"6003139266461","name":"Live music"}]}],
    }),
});
const data = await res.json();

Response 200

{
  "data": { "id": "a51f…", "meta_adset_id": "604839271650", "name": "[CK] … · AdSet #1" },
  "request_id": "…"
}

Gesperrt (→ 422 validation_error mit details.locked_fields, wenn gesendet): name, status, optimization_goal, billing_event, bid_strategy, promoted_object sowie targeting.geo_locations / publisher_platforms / facebook_positions / instagram_positions / device_platforms. Das Anlegen ist nur unter einer AKTIVEN Ziel-Kampagne möglich; ist die Kampagne deaktiviert, kommt 409 conflict. Erfordert zudem vollständiges Onboarding (Token verifiziert, Werbekonto, Page, Instagram-Konto, DSA/legal_name); fehlt etwas → 422 mit details.missing.

PATCH

/v1/meta/adsets/{id}

Aktualisiert Budget, Laufzeit oder Status eines Ad Sets. Partielles Update — nur gesendete Felder ändern sich.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Ad-Set-ID (aus POST/GET).

Body-Parameter

Name	Typ	Pflicht	Beschreibung
daily_budget_cents	integer (Cent)	optional	Neues Tagesbudget.
lifetime_budget_cents	integer (Cent)	optional	Neues Laufzeitbudget.
start_time	string (ISO 8601)	optional	Neuer Startzeitpunkt.
end_time	string (ISO 8601)	optional	Neuer Endzeitpunkt.
status	enum	optional	ACTIVE \| PAUSED. Kein Mengen-Limit mehr; Aktivieren setzt nur einen aktiven Zugang + eine aktive Ziel-Kampagne voraus.

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/meta/adsets/${id}`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({

    }),
});
const data = await res.json();

Response 200

{
  "data": { "id": "a51f…", "status": "ACTIVE", "daily_budget_cents": 5000, "meta_adset_id": "604839271650" },
  "request_id": "…"
}

Gesperrt (→ 422): optimization_goal, billing_event, targeting u. a. (siehe POST). Kein Mengen-Limit. Jede Änderung (auch Pausieren) erfordert eine aktive Ziel-Kampagne, sonst 409 conflict. Archivieren (DELETE) bleibt möglich.

DELETE

/v1/meta/adsets/{id}

Archiviert ein Ad Set (status=ARCHIVED) bei uns und bei Meta.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Ad-Set-ID.

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/meta/adsets/${id}`, {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{ "data": { "id": "a51f…", "status": "ARCHIVED" }, "request_id": "…" }

Archiviert statt hart zu löschen.