Appearance
campaigns
9 endpoints.
GET /api/v1/campaigns
List Campaigns
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | query | no |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/campaigns/{campaign_id}/ads
List Campaign Ads
Ads directly under one campaign (skips the ad-set hop — the Ad model already carries its owning campaign_id, same field the Ads grid filters on). Feeds the Deals page's "Import campaign leads" ad picker. Each ad reports its own lead count so the picker can show which ads are worth importing before the user commits.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/campaigns/{campaign_id}/adsets
List Adsets
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/campaigns/{campaign_id}/adsets/{adset_id}/ads
List Ads
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string | |
adset_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/campaigns/{campaign_id}/overview
Campaign Overview
Everything about ONE live campaign, the way Meta shows it.
2026-09-08, owner: "When clicking a view button on a live campaign in the cavet dropdown, it should bring a pop up to show all the details of the live campaign in a similar way to what would be shown when viewing a live campaign on meta. All the important details, captions, headlines, cost, ad image etc. should be shown."
campaign_id is the META campaign id, as it is on /reports/campaign/{id}/insights — the same field the grid row carries.
Deliberately NOT the same thing as "View process": that reopens the run that BUILT a campaign and only exists for one this portal has not published yet. This reads the campaign as it stands on Meta, which is the only thing a published campaign has. The two never appear on the same row (see the show_when on both buttons in grid_social.py).
Refuses a draft outright rather than half-answering: a draft: id names a campaign that exists nowhere but this database, so there is nothing on Meta to describe.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/campaigns/{campaign_id}/settings
Edit Campaign Settings
Edit a LIVE campaign on Meta, the way Ads Manager's "Edit" does.
2026-09-10, owner: "add an edit button in the dropdown cavet of the campaigns that opens a page to edit the live campaign details as it would be done when clicking edit campaign on meta". The panel behind it is CampaignEditModal; it prefills from :func:campaign_overview, so this endpoint only ever receives what changed.
campaign_id is the META id, as on the grid row and on /overview — NOT Campaign.id. (creatives.edit_campaign takes the local row id and covers name/status/budget only; it predates this and is left alone.)
WHAT IS DELIBERATELY NOT HERE:
- Objective and buying type. Meta fixes both at creation. They are shown on the panel, greyed, for the same reason Ads Manager shows them: the first question about a campaign's results is what it was told to optimise.
- Status. Activate / Pause sit two rows below Edit in the same dropdown and they carry the new status DOWN to the ad set and every ad (
grid_social._propagate_campaign_status) — a campaign switched on over a paused ad set delivers nothing. A second on/off switch here would do the shallower thing under the same word. - Switching daily <-> lifetime. The amount of whichever budget the campaign carries is editable; which KIND it is, is not. Meta's own rules for the swap differ by objective and bid strategy (a lifetime budget needs an end date, some strategies forbid one), and getting it wrong on a live campaign changes what it spends. A campaign budgeted on its ad sets shows no budget field at all, which is what Ads Manager greys out too.
Everything sent goes to Meta first; the local campaigns row is only mirrored once Graph has accepted, so a rejected edit never leaves this database claiming a budget Facebook does not have.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
Request body
json
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"daily_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Daily Budget"
},
"lifetime_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Lifetime Budget"
},
"spend_cap": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Spend Cap"
},
"bid_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bid Strategy"
},
"special_ad_categories": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Special Ad Categories"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
},
"stop_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Stop Time"
}
},
"type": "object",
"title": "CampaignSettingsEdit",
"description": "The campaign-level settings Ads Manager's own \"Edit campaign\" panel edits.\n\nEvery field is optional and only the ones actually sent are written, so the\npanel can PUT the diff rather than the whole campaign — sending an unchanged\n``bid_strategy`` back to a campaign that has no campaign budget is a Meta\nerror, and re-sending a budget nobody touched is a live spend change.\n\nBudgets and the spend cap are in MINOR units (cents), which is how Meta\nstates them everywhere else in this file and how the grid's Budget column\nalready reads them. The panel multiplies what the operator typed."
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/campaigns/bulk/status
Bulk Update Status
Bulk update campaign statuses on Meta.
Request body
json
{
"properties": {
"campaign_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Campaign Ids"
},
"status": {
"type": "string",
"title": "Status"
}
},
"type": "object",
"required": [
"campaign_ids",
"status"
],
"title": "BulkStatusUpdate"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/campaigns/{campaign_id}/status
Update Campaign Status
Update a campaign's status on Meta (ACTIVE, PAUSED, DELETED).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
Request body
json
{
"properties": {
"status": {
"type": "string",
"title": "Status"
}
},
"type": "object",
"required": [
"status"
],
"title": "CampaignStatusUpdate"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/campaigns/{campaign_id}/publish-live
Publish Campaign Live
Activate an entire campaign tree on Meta — the campaign, its ad sets and its ads all set to ACTIVE in one call.
Backs the "Make live" action in the Create-Campaign success menu: a campaign created PAUSED won't deliver until every level is ACTIVE, so flipping just the campaign isn't enough. campaign_id is the Meta campaign id (what the launch flow has on hand), so we match on the campaign_id column. Per-entity errors are collected rather than aborting, so one bad ad can't block the rest going live.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}