Worlds / Marketing and ads

Meta Ads API

A local Meta Ads account with campaigns, ad sets, ads, custom audiences, budgets and review states. Test the agent that adjusts budgets, swaps audiences and handles rejected ads.

Base path: /v21.0
Auth: Access token query parameter or bearer token, the world key
Endpoints: 12
Status: Active today

This reference previews the surface the Meta Ads world serves in the closed beta. Paths mirror the public Meta Ads API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_META_ADS_URL`	This world's origin followed by `/v21.0`
`WORLDS_API_KEY`	The world key, accepted wherever Meta Ads expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_META_ADS_URL;
const token = process.env.WORLDS_API_KEY;

const res = await fetch(
  base + "/act_1234567890/campaigns?fields=name,status,objective&access_token=" + token
);
const { data } = await res.json();

API reference

12 of 12

Campaigns

Top-level ad objectives.

GET/v21.0/act_{ad_account_id}/campaignsList campaigns
POST/v21.0/act_{ad_account_id}/campaignsCreate a campaign
GET/v21.0/{campaign_id}Read a campaign
POST/v21.0/{campaign_id}Update a campaign

Fields · 5

`id`	string	Campaign id
`name`	string	Campaign name
`objective`	string	OUTCOME_SALES, OUTCOME_LEADS and so on
`status`	string	ACTIVE, PAUSED, DELETED or ARCHIVED
`daily_budget`	string	Daily budget in cents

Ad sets

Targeting, budget and schedule for ads.

GET/v21.0/act_{ad_account_id}/adsetsList ad sets
POST/v21.0/act_{ad_account_id}/adsetsCreate an ad set
POST/v21.0/{adset_id}Update an ad set

Fields · 6

`id`	string	Ad set id
`name`	string	Name
`campaign_id`	string	Parent campaign
`status`	string	ACTIVE or PAUSED
`targeting`	object	Audience targeting
`optimization_goal`	string	What delivery optimizes for

Creative shown to people.

GET/v21.0/act_{ad_account_id}/adsList ads
POST/v21.0/act_{ad_account_id}/adsCreate an ad
POST/v21.0/{ad_id}Update an ad

Fields · 5

`id`	string	Ad id
`name`	string	Name
`adset_id`	string	Parent ad set
`status`	string	ACTIVE or PAUSED
`creative`	object	Creative reference

Insights

Spend and performance metrics.

GET/v21.0/act_{ad_account_id}/insightsAccount insights
GET/v21.0/{campaign_id}/insightsCampaign insights

Fields · 5

`impressions`	string	Impressions
`clicks`	string	Clicks
`spend`	string	Amount spent
`cpc`	string	Cost per click
`date_start`	string	Range start

Test workflow

Prepare. Select the Meta Ads setup for your workflow and review its starting records, including campaigns, ad sets, ads.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Retarget 30d daily_budget is $60
Winback 180d excludes Purchasers 180d
Holiday Video ads Paused, not deleted
Campaign budgets unchanged
No new ad set Active

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Meta Ads
version: 2
connector: meta-ads
seed: meta-ads-starter
mode: isolated
policy: >
  Tidy delivery before the weekend. Raise Retarget 30d to $60 a day. Winback
  must exclude Purchasers 180d. Pause rejected ads, do not delete them.
tasks:
  - id: change-an-ad-set-daily-budget
    prompt: Change an ad set daily budget
  - id: swap-the-audience-on-an-ad-set
    prompt: Swap the audience on an ad set
  - id: pause-ads-that-were-rejected-and-draft-a-fix
    prompt: Pause ads that were rejected and draft a fix
expected:
  - Retarget 30d daily_budget is $60
  - Winback 180d excludes Purchasers 180d
  - "Holiday Video ads Paused, not deleted"
  - Campaign budgets unchanged
  - No new ad set Active
scenarios:
  - rate-limited
  - ads-api-throttled
  - token-expired

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	Error code 17, user request limit reached
`ads-api-throttled`	Error code 80004 on too many calls to the ad account
`token-expired`	OAuthException code 190, the access token expired
`ad-rejected`	The edited ad returns to review and is rejected again
`spend-cap-hit`	Delivery stops when the account spend cap is reached

Starting data

Start each run from the same records and relationships. The overview below describes the Meta Ads starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
campaigns	6 with Sales and Traffic objectives
ad sets	18 with daily and lifetime budgets
ads	40 across Active, In review, Rejected and Paused
custom audiences	Purchasers 180d, Site visitors 30d, Lookalike 1%
ad account	Spend cap set, USD

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Campaigns records

Campaigns

Top-level ad objectives.

Field	Type	Meaning / relationship
`id`	string	Campaign id
`name`	string	Campaign name
`objective`	string	OUTCOME_SALES, OUTCOME_LEADS and so on
`status`	string	ACTIVE, PAUSED, DELETED or ARCHIVED
`daily_budget`	string	Daily budget in cents

json · illustrative record shape

{
  "id": "<Campaign id>",
  "name": "<Campaign name>",
  "objective": "<OUTCOME_SALES, OUTCOME_LEADS and so on>",
  "status": "<ACTIVE, PAUSED, DELETED or ARCHIVED>",
  "daily_budget": "<Daily budget in cents>"
}

See campaigns operations

Ad sets records

Ad sets

Targeting, budget and schedule for ads.

Field	Type	Meaning / relationship
`id`	string	Ad set id
`name`	string	Name
`campaign_id`	string	Parent campaign
`status`	string	ACTIVE or PAUSED
`targeting`	object	Audience targeting
`optimization_goal`	string	What delivery optimizes for

json · illustrative record shape

{
  "id": "<Ad set id>",
  "name": "<Name>",
  "campaign_id": "<Parent campaign>",
  "status": "<ACTIVE or PAUSED>",
  "targeting": {},
  "optimization_goal": "<What delivery optimizes for>"
}

See ad sets operations

Ads records

Creative shown to people.

Field	Type	Meaning / relationship
`id`	string	Ad id
`name`	string	Name
`adset_id`	string	Parent ad set
`status`	string	ACTIVE or PAUSED
`creative`	object	Creative reference

json · illustrative record shape

{
  "id": "<Ad id>",
  "name": "<Name>",
  "adset_id": "<Parent ad set>",
  "status": "<ACTIVE or PAUSED>",
  "creative": {}
}

See ads operations

Insights records

Insights

Spend and performance metrics.

Field	Type	Meaning / relationship
`impressions`	string	Impressions
`clicks`	string	Clicks
`spend`	string	Amount spent
`cpc`	string	Cost per click
`date_start`	string	Range start

json · illustrative record shape

{
  "impressions": "<Impressions>",
  "clicks": "<Clicks>",
  "spend": "<Amount spent>",
  "cpc": "<Cost per click>",
  "date_start": "<Range start>"
}

See insights operations

See the Meta Ads world in the catalog