Worlds / Marketing and ads

Google Ads API

A local Google Ads account with campaigns, budgets, ad groups, keywords, bidding strategies and ad policy status. Test the agent that pauses, rebudgets and fixes disapproved ads.

Base path: /v17/customers/{customerId}
Auth: OAuth 2.0 bearer token plus developer token, the world key
Endpoints: 9
Status: Active today

This reference previews the surface the Google Ads world serves in the closed beta. Paths mirror the public Google 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_GOOGLE_ADS_URL`	This world's origin followed by `/v17/customers/{customerId}`
`WORLDS_API_KEY`	The world key, accepted wherever Google Ads expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · google-ads-api

import { GoogleAdsApi } from "google-ads-api";

const api = new GoogleAdsApi({
  client_id: "id",
  client_secret: "secret",
  developer_token: process.env.WORLDS_API_KEY,
  base_url: process.env.WORLDS_GOOGLE_ADS_URL,
});
const customer = api.Customer({ customer_id: "1234567890", refresh_token: "token" });
const rows = await customer.query("SELECT campaign.id, campaign.name FROM campaign");

API reference

9 of 9

Campaigns

Ad campaigns with budget and status.

POST/v17/customers/{customerId}/googleAds:searchQuery campaigns with GAQL
POST/v17/customers/{customerId}/googleAds:searchStreamStream query results
POST/v17/customers/{customerId}/campaigns:mutateCreate, update or remove campaigns

Fields · 5

`resourceName`	string	customers/{id}/campaigns/{id}
`name`	string	Campaign name
`status`	string	ENABLED, PAUSED or REMOVED
`advertisingChannelType`	string	SEARCH, DISPLAY and so on
`campaignBudget`	string	Budget resource name

Ad groups

Groups of ads and keywords inside a campaign.

POST/v17/customers/{customerId}/adGroups:mutateCreate, update or remove ad groups
POST/v17/customers/{customerId}/googleAds:searchQuery ad groups with GAQL

Fields · 5

`resourceName`	string	Ad group resource name
`name`	string	Ad group name
`status`	string	ENABLED, PAUSED or REMOVED
`campaign`	string	Parent campaign
`cpcBidMicros`	string	Default bid in micros

Campaign budgets

Daily spend limits shared by campaigns.

POST/v17/customers/{customerId}/campaignBudgets:mutateCreate or update budgets
POST/v17/customers/{customerId}/googleAds:searchQuery budgets with GAQL

Fields · 4

`resourceName`	string	Budget resource name
`name`	string	Budget name
`amountMicros`	string	Daily amount in micros
`deliveryMethod`	string	STANDARD or ACCELERATED

Reporting

Performance metrics returned by GAQL queries.

POST/v17/customers/{customerId}/googleAds:searchRun a report query
POST/v17/customers/{customerId}/googleAds:searchStreamStream a report

Fields · 5

`metrics.impressions`	string	Impressions
`metrics.clicks`	string	Clicks
`metrics.costMicros`	string	Spend in micros
`metrics.conversions`	number	Conversions
`segments.date`	string	Day

Test workflow

Prepare. Select the Google Ads setup for your workflow and review its starting records, including campaigns, ad groups, campaign budgets.
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

Brand US budget at $180 a day
Generic Shoes campaign Paused
PMax Holiday budget still $300
No budget changed by more than 20%
Shared budgets untouched

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 · Google Ads
version: 2
connector: google-ads
seed: google-ads-starter
mode: isolated
policy: >
  Rebalance spend for the weekend. Raise Brand US by up to 20%. Pause Generic
  Shoes, its CPA doubled. Do not move any budget more than 20% without
  approval.
tasks:
  - id: raise-or-lower-a-campaign-budget-inside-the-limit
    prompt: Raise or lower a campaign budget inside the limit
  - id: pause-underperforming-keywords
    prompt: Pause underperforming keywords
  - id: fix-and-resubmit-a-disapproved-ad
    prompt: Fix and resubmit a disapproved ad
expected:
  - Brand US budget at $180 a day
  - Generic Shoes campaign Paused
  - PMax Holiday budget still $300
  - "No budget changed by more than 20%"
  - Shared budgets untouched
scenarios:
  - quota-exhausted
  - partial-failure
  - policy-violation

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
`quota-exhausted`	RESOURCE_EXHAUSTED on the next mutate
`partial-failure`	One operation in the batch fails, the rest apply
`policy-violation`	PolicyFindingError on the edited ad text
`token-expired`	The OAuth refresh fails and the call returns UNAUTHENTICATED

Starting data

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

Records	Starting setup
campaigns	8 Search and Performance Max, Enabled and Paused
campaign budgets	Daily, two shared between campaigns
ad groups	24 with 300 keywords
ads	60 responsive search ads, 3 disapproved
bidding strategies	Maximize conversions and Target CPA

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

Ad campaigns with budget and status.

Field	Type	Meaning / relationship
`resourceName`	string	customers/{id}/campaigns/{id}
`name`	string	Campaign name
`status`	string	ENABLED, PAUSED or REMOVED
`advertisingChannelType`	string	SEARCH, DISPLAY and so on
`campaignBudget`	string	Budget resource name

json · illustrative record shape

{
  "resourceName": "<customers/{id}/campaigns/{id}>",
  "name": "<Campaign name>",
  "status": "<ENABLED, PAUSED or REMOVED>",
  "advertisingChannelType": "<SEARCH, DISPLAY and so on>",
  "campaignBudget": "<Budget resource name>"
}

See campaigns operations

Ad groups records

Ad groups

Groups of ads and keywords inside a campaign.

Field	Type	Meaning / relationship
`resourceName`	string	Ad group resource name
`name`	string	Ad group name
`status`	string	ENABLED, PAUSED or REMOVED
`campaign`	string	Parent campaign
`cpcBidMicros`	string	Default bid in micros

json · illustrative record shape

{
  "resourceName": "<Ad group resource name>",
  "name": "<Ad group name>",
  "status": "<ENABLED, PAUSED or REMOVED>",
  "campaign": "<Parent campaign>",
  "cpcBidMicros": "<Default bid in micros>"
}

See ad groups operations

Campaign budgets records

Campaign budgets

Daily spend limits shared by campaigns.

Field	Type	Meaning / relationship
`resourceName`	string	Budget resource name
`name`	string	Budget name
`amountMicros`	string	Daily amount in micros
`deliveryMethod`	string	STANDARD or ACCELERATED

json · illustrative record shape

{
  "resourceName": "<Budget resource name>",
  "name": "<Budget name>",
  "amountMicros": "<Daily amount in micros>",
  "deliveryMethod": "<STANDARD or ACCELERATED>"
}

See campaign budgets operations

Reporting records

Reporting

Performance metrics returned by GAQL queries.

Field	Type	Meaning / relationship
`metrics.impressions`	string	Impressions
`metrics.clicks`	string	Clicks
`metrics.costMicros`	string	Spend in micros
`metrics.conversions`	number	Conversions
`segments.date`	string	Day

json · illustrative record shape

{
  "metrics.impressions": "<Impressions>",
  "metrics.clicks": "<Clicks>",
  "metrics.costMicros": "<Spend in micros>",
  "metrics.conversions": 1,
  "segments.date": "<Day>"
}

See reporting operations

See the Google Ads world in the catalog