URL: /capabilities/run-ads · Id: `page:/capabilities/run-ads`

# Run ads

> Clicks and cost before you spend, then the campaign on your own ad account, stopped by the agent when it does not pay.

What would 500 clicks on my terms cost? Your agent prices them before you spend, runs the test on your own ad account, and stops spend that does not pay.

```text title="Run ads · Ask"
What would 500 clicks on rent collection software cost?
Run the test on my Google account, and stop it if it does not pay.
```

```ts title="Run ads · SDK"
import { $ } from 'startup-builder'

await $.Keyword.measure({ keyword: 'rent collection software', locale: 'en-US', venue: 'google-search' })   // volume and cost per click, the price of the test
await $.Integration.connect({ system: 'ads', scope: 'startup', grants: ['campaigns', 'budgets', 'reports'], venue: 'google-search' })   // your ad account, once
await $.Mandate.authorize({ agent: 'agents/agent_7', verb: 'Campaign.update', limit: { spend: 2050, currency: 'USD' }, for: 'parties/party_1' })   // the stop rule: spend to zero when a paid customer costs more than first-year margin
return await $.Campaign.start({ campaign: 'paid-search', budget: { amount: 2050, currency: 'USD', per: 'test' } })   // the 500-click test on your account · Not live yet, gaps #2
```

```json title="Run ads · Response · sample"
{
  "$type": "Campaign",
  "play": "paid-search",
  "venue": "google-search",
  "forecast": {
    "terms": 6,
    "match": "exact",
    "averageCpc": 4.1,
    "clicks": 500,
    "cost": 2050
  },
  "alreadyPaying": {
    "terms": 4,
    "longestRunningAd": "since 2026-03-02"
  },
  "budget": {
    "amount": 2050,
    "currency": "USD",
    "daily": 230
  },
  "stopRule": "500 clicks spent and projected cost per paid customer above first-year margin",
  "day3": {
    "clicks": 171,
    "spend": 702.4,
    "signups": 4,
    "costPerSignup": 175.6,
    "projectedCostPerPaid": 702.4,
    "firstYearMargin": 1140,
    "verdict": "keep running"
  }
}
```

| First run | Status | Runs by | Connect once |
| --- | --- | --- | --- |
| Forecast: $0.09; the spend is yours | Coming | API · browser agent | Your Google and Meta ad accounts, once. LinkedIn, Reddit and X sign in for the browser agent. |

## What you get
| Field | What it says |
| --- | --- |
| Term | The exact term the campaign bids on, with its match type. |
| Forecast | Clicks, cost per click and spend for a month at your bid, read before any spend. |
| Test budget | 500 clicks times the terms’ cost per click: the fewest clicks that read a signup rate. |
| Spend | What the campaign spent, by day and by ad, read from your ad account. |
| Signups | Signups your site recorded from each ad’s clicks. |
| Cost per signup | Spend divided by signups: the first number to read, in week 1. |
| Projected cost per paid customer | Cost per signup divided by your signup-to-paid rate. A blank reads unknown until the first customer pays. |
| Stop rule | The line you set once. When the test is spent and the projected cost per paid customer passes it, spend goes to zero and the report says why. |

## How it runs
| When | What happens | Runs by | Your part | Takes |
| --- | --- | --- | --- | --- |
| Day 0 | Read who already pays for your terms and the ads they keep running, from Size up competitors | API | nothing | minutes |
| Day 0 | Forecast clicks and cost for the exact terms nobody pays for yet, and for the rest ([Ad cost forecast](#ad-forecast)) | API | nothing | minutes |
| Day 0 | Connect your ad account and set the first-year margin the stop rule reads ([Stop rule](#stop-rule)) | API | connect once and approve the budget, about 15 min | minutes |
| Day 0 | Turn your saved list into an audience and a lookalike ([Audience from your list](#audience-from-your-list)) | API | nothing | up to a day for the audience to fill |
| Day 1 | Launch the campaign with the ad kit you approved, on Meta by API ([Run on your account](#run-on-your-account)) | API | nothing | first clicks within a day |
| Day 1 | Build the Google, LinkedIn, Reddit or X campaign in its ad manager, signed in as you ([Run where there is no API](#run-by-browser-agent)) | browser agent | nothing | first clicks within a day of the ad’s review |
| Daily | Read spend, clicks and signups for each ad ([Spend and results](#spend-and-results)) | API | nothing | the same day |
| Daily | Move budget to the ad that wins and pause the rest ([Pause or rebudget](#pause-or-rebudget)) | API · browser agent | nothing | the same day |
| At 500 clicks | Project the cost per paid customer, then keep the winner running or set spend to zero ([Stop rule](#stop-rule)) | API · browser agent | read the verdict, about 5 min | the day the test is spent |

## Jobs inside it
| Job | What it returns | Price | Status | Runs by |
| --- | --- | --- | --- | --- |
| <a id="ad-forecast"></a>Ad cost forecast | Clicks, cost per click and spend for your exact terms at your bid, before any spend | $0.09 a forecast | Coming | API |
| <a id="audience-from-your-list"></a>Audience from your list | Your saved list of first customers as an ad audience, and a lookalike built from it | free | Coming | API |
| <a id="run-on-your-account"></a>Run on your account | The campaign, ad sets and ads live on your Meta or Google account | free; the spend is yours | Coming | API |
| <a id="run-by-browser-agent"></a>Run where there is no API | Google campaign setup and LinkedIn, Reddit and X campaigns built in each ad manager, signed in as you | about 2¢ a step; the spend is yours | Coming | browser agent |
| <a id="spend-and-results"></a>Spend and results | What each campaign and ad spent and what it brought, daily | free | Coming | API |
| <a id="pause-or-rebudget"></a>Pause or rebudget | Daily budget moved to the ad that wins, and losing ads paused | free | Coming | API |
| <a id="stop-rule"></a>Stop rule | Spend set to zero when the projected cost per paid customer passes your first-year margin | free | Coming | API |

## Where and how it runs
| Where it works | How it runs | Connect once |
| --- | --- | --- |
| Google Search, Bing, Facebook, Instagram, LinkedIn, Reddit, X | API · browser agent | Your Google and Meta ad accounts, once. LinkedIn, Reddit and X sign in for the browser agent. |

Your agent acts as you on every Venue you authorize. Where a Venue has no API, a browser agent signs in as you and does the steps.

## Plays that use it
| Play | Strategy that runs it |
| --- | --- |
| [Paid search](/plays/paid-search) | [Paid](/strategy/paid) |
| [Paid social](/plays/paid-social) | [Paid](/strategy/paid) |
| [Smoke test](https://startupbuilder.dev/workflows/plays/smoke-test) | [Paid](/strategy/paid) |
| [Retargeting](/plays/retargeting) | [Paid](/strategy/paid) |
| [Promote winners](/plays/promote-winners) | [Paid](/strategy/paid) |

## Reference
| Tool | Runs today |
| --- | --- |
| <Op verb="Campaign.create" /> | Coming |
| <Op verb="Keyword.measure" /> | Coming |
| <Op verb="Audience.create" /> | Coming |
| <Op verb="Campaign.update" /> | Coming |
| <Op verb="Mandate.authorize" /> | Coming |
| <Op verb="Integration.connect" /> | Coming |