Campaign
Schema, including its fields, nested structure, and relationships
Definition
A Campaign represents an AB test, experiment or rollout. It defines the high-level setup (name, type) and contains one or more Variation Groups, each of which splits traffic and may apply feature modifications. Campaigns typically reference governance resources (e.g., Goals) and operate under one Project.
Payload Properties
A campaign has many properties. When creating or updating a campaign, the payload can include the following fields:
id(String, optional) – The campaign's unique ID.Include this only when updating an existing campaign.project_id(String, required) — Reference to the owning Project ID (e.g.,"$p1.id").name(String, required) — Campaign display name.description(String, optional) — Freeform description.type(String, required) — Experiment type. Common:"ab".variation_groups(Array<VariationGroup>, required) — One or more variation groups (see Variation Group page). Each Variation Group supports:name(String, optional)variations(Array<Variation>, required)name(String, required)reference(Boolean, required) — exactly onetrueper groupallocation(Integer, required) — 0–100; group total must be 100modifications(Object, optional)type(String, required when present) — e.g.,"FLAG"value(Object, required when present) — key/value pairs (flag/config)
targeting(Object, optional)targeting_groups(Array, optional; OR between groups)Each with
targetings(Array, AND within the group):key(String, required)operator(String, required) — e.g.,EQUALS,IN,CONTAINSvalue(Any, required)
goal_ids(Array<String>, optional) — If supported, IDs of goals attached to measure this campaign (e.g.,["$g1.id"]).
Notes • Each variation group manages its own traffic allocation and targeting. • A campaign can be created without goals; analytics may still attribute conversions via your tracking setup.
Example Campaign Payload: Below is an example of a complex campaign payload for a ab campaign (type "ab"). This illustrates many of the fields described above:
{
"project_id": "project_id",
"name": "Checkout Button Experiment",
"description": "Test new button copy and color",
"type": "ab",
"variation_groups": [
{
"name": "Main Split",
"variations": [
{ "name": "Original", "reference": true, "allocation": 50 },
{
"name": "Variation 1",
"reference": false,
"allocation": 50,
"modifications": {
"type": "FLAG",
"value": {
"button-color": "blue",
"button-copy": "Buy now"
}
}
}
],
"targeting": {
"targeting_groups": [
{
"targetings": [
{ "key": "release", "operator": "EQUALS", "value": "v1.0.0" }
]
}
]
}
}
]
}
Response Fields
When a Campaign is returned by the API/Resource Loader, you’ll receive read-only metadata plus the resolved variation groups and variations.
id(String) — Unique campaign identifier.project_id(String) — Owning project ID.name(String) — Campaign name.description(String) — Campaign description.type(String) — Experiment type (e.g.,"ab").status(String) — Lifecycle state (e.g.,"draft","online","paused").created_at(String, ISO-8601) — Creation timestamp, e.g.,"2025-11-12T11:26:42+00:00".updated_at(String, ISO-8601) — Last update timestamp.variation_groups(Array<Object>) — Resolved groups containing:id(String) — Group ID.name(String) — Group name.targeting(Object) — Resolved targeting rules.variations(Array<Object>) — Resolved variations containing:id(String) — Variation ID.name(String) — Variation name.reference(Boolean) — Control indicator.allocation(Integer) — Allocated traffic (0–100).modifications(Object) — Resolved modifications:type(String) — e.g.,"FLAG".value(Object|Array) — The effective flag/config values.
In some cases the API may return an empty object/array for the control/reference variant if no modifications apply.
Example Response
{
"created_at": "2025-11-12T11:26:42+00:00",
"description": "Loaded from resource loader",
"id": "campaign_id",
"name": "Resource loader Campaign - with targeting & existing flag",
"project_id": "project_id",
"status": "draft",
"type": "ab",
"updated_at": "2025-11-12T11:26:42+00:00",
"variation_groups": [
{
"id": "variation_group_id",
"name": "variation group name",
"targeting": {
"targeting_groups": [
{
"targetings": [
{
"key": "release",
"operator": "EQUALS",
"value": "v1.0.0"
}
]
}
]
},
"variations": [
{
"allocation": 50,
"id": "variation_id",
"modifications": {
"type": "FLAG",
"value": []
},
"name": "Original",
"reference": true
},
{
"allocation": 50,
"id": "variation_id_1",
"modifications": {
"type": "FLAG",
"value": {
"background-flag": "blue"
}
},
"name": "Variation 1",
"reference": false
}
]
}
]
}Tip • If your platform supports attaching goals to campaigns, you may also see a
goal_idsarray on the campaign (and possibly goal metadata in separate endpoints).
Error Codes
Error scenarios for campaigns largely follow the general codes:
InvalidPayload – The campaign payload is missing required fields or has invalid values (e.g., missing name or type).
ParentNotFound – (Not usually applicable to campaigns since they have no parent in this schema; this might be returned if an account or environment context is wrong, but not in the resource schema context of parent-child).
PermissionDenied – The user lacks permission to create or modify campaigns (for instance, not having the rights to create campaigns in the account).
DuplicateRef – A campaign with the same reference already exists. For example, trying to create a campaign with a name or key that conflicts with an existing one could trigger this.
InvalidDependency – If the campaign references something that doesn’t exist. This is rare at the campaign level, but could occur if sub_tests or audiences reference invalid IDs (e.g., an audience ID that is not found).
Last updated
Was this helpful?