Appearance
adsets
9 endpoints.
GET /api/v1/adsets/targeting-search/{account_id}
Targeting Search
Autocomplete detailed-targeting terms (interests, behaviours, demographics).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
q | query | 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/adsets/geo-search/{account_id}
Geo Search
Search ad geo locations (countries, regions, cities, zips).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
q | query | yes | string | |
location_types | 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/adsets/locale-search/{account_id}
Locale Search
Search ad locales (languages).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
q | query | 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/adsets/custom-audiences/{account_id}
Custom Audiences
List custom + lookalike audiences for include/exclude targeting.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_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/adsets/saved-audiences/{account_id}
Saved Audiences
List saved audiences.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_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/adsets/pixels/{account_id}
Pixels
List Meta Pixels / datasets for conversion optimization.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_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/adsets/account-status/{account_id}
Account Status
Billing / verification status for the ad composer's Payment + Verification cards: whether a funding source is attached, the account is active, etc.
Meta only lets advertisers add a payment method or verify a phone number in its own UI, so the composer reads the current state here and deep-links out to finish setup — never returns an error that would block building the ad.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_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"
}POST /api/v1/adsets/reach-estimate/{account_id}
Reach Estimate
Audience-size / delivery estimate for the current targeting spec.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"optimization_goal": {
"type": "string",
"title": "Optimization Goal"
},
"targeting": {
"additionalProperties": true,
"type": "object",
"title": "Targeting"
}
},
"type": "object",
"required": [
"optimization_goal",
"targeting"
],
"title": "ReachEstimateRequest"
}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/adsets/{account_id}
Create Ad Set
Create an ad set on Meta (under an existing or new campaign) and mirror it locally so it appears in the Ad Sets grid immediately.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"campaign_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign Id"
},
"new_campaign": {
"anyOf": [
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"objective": {
"type": "string",
"title": "Objective",
"default": "OUTCOME_TRAFFIC"
},
"special_ad_categories": {
"items": {
"type": "string"
},
"type": "array",
"title": "Special Ad Categories",
"default": []
},
"buying_type": {
"type": "string",
"title": "Buying Type",
"default": "AUCTION"
},
"campaign_budget_optimization": {
"type": "boolean",
"title": "Campaign Budget Optimization",
"default": false
},
"daily_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Daily Budget"
},
"lifetime_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Lifetime Budget"
},
"bid_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bid Strategy"
}
},
"type": "object",
"required": [
"name"
],
"title": "NewCampaign",
"description": "Optional inline campaign to create the ad set under."
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"title": "Name"
},
"status": {
"type": "string",
"title": "Status",
"default": "PAUSED"
},
"daily_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Daily Budget"
},
"lifetime_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Lifetime Budget"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "End Time"
},
"optimization_goal": {
"type": "string",
"title": "Optimization Goal"
},
"billing_event": {
"type": "string",
"title": "Billing Event"
},
"destination_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Destination Type"
},
"promoted_object": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Promoted Object"
},
"attribution_spec": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attribution Spec"
},
"frequency_control_specs": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Frequency Control Specs"
},
"is_dynamic_creative": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Dynamic Creative"
},
"bid_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bid Strategy"
},
"bid_amount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bid Amount"
},
"bid_constraints": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Bid Constraints"
},
"targeting": {
"additionalProperties": true,
"type": "object",
"title": "Targeting"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"name",
"optimization_goal",
"billing_event",
"targeting"
],
"title": "AdSetCreate"
}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"
}