URL: /code/data/ads · Id: `page:/code/data/ads`

# Ads

> An Ad is “one paid or house placement promoting an offer to an Audience”: read the ones your rivals keep paying for first.

An [Ad](https://startupbuilder.dev/business/nouns/ad) is “one paid or house placement promoting an [offer](https://startupbuilder.dev/business/nouns/offer) to an [Audience](https://startupbuilder.dev/business/nouns/audience)”: read the ones your rivals keep paying for first.

- **Noun:** [Ad](https://startupbuilder.dev/business/nouns/ad)
- **Calls:** 1
- **Emits:** `Ad.found`

A Data Verb reads the market and returns a reading. A Software Verb changes your records and emits an Event. Every call here is a Data Verb: it reads, and it changes a record only where its Effects say so.

## Properties
| Field | Type | What `null` means |
| --- | --- | --- |
| `ads` | `Ad[]` | Never null: empty when none ran, at $0; absent with `countOnly`. |
| `ads[].advertiser` | `{ name: string; hostname: Hostname \| null }` | Never null; `hostname: null` when the page names no site. |
| `ads[].venue` | [`VenueId`](/code/data/types#venueid) | Never null. |
| `ads[].format` | `'text' \| 'image' \| 'video' \| 'carousel'` | Never null. |
| `ads[].headline` | `string \| null` | The format has no headline. |
| `ads[].body` | `string \| null` | The format has no body copy. |
| `ads[].cta` | `string \| null` | No button. |
| `ads[].landingUrl` | `string \| null` | The library does not show it. |
| `ads[].mediaUrl` | `string \| null` | A text ad, or the library does not serve the file. |
| `ads[].firstSeen` | `string \| null`, in date | The library does not show a start date. |
| `ads[].lastSeen` | `string \| null`, in date | The library does not show it. |
| `ads[].daysRunning` | `number \| null`, in days | No start date, so unknown; never zero. |
| `ads[].transparencyUrl` | `string \| null` | The site’s library has no page for it. |
| `ads[]` | [`Observed`](/code/data/types#observed) | Each ad also carries `observedAt` and `method`. |
| `total` | `number \| null`, in ads | The library reports no total. |
| `after` | [`Cursor`](/code/data/types#cursor) | The last page: there are no more rows. |
| `cost` | [`Cost`](/code/data/types#cost), in USD | Never null. In try mode `usd` is 0 and `maxUsd` is what the call would have cost. |

## Object
```json
{
  "ads": [
    {
      "advertiser": {
        "name": "RentRival",
        "hostname": "rentrival.example"
      },
      "venue": "facebook",
      "format": "image",
      "headline": "Stop chasing rent in spreadsheets",
      "body": "Owners get statements on the 1st. Free for 14 days.",
      "cta": "Sign up",
      "landingUrl": "https://rentrival.example/pm",
      "mediaUrl": null,
      "firstSeen": "2026-06-02",
      "lastSeen": "2026-10-26",
      "daysRunning": 146,
      "transparencyUrl": null,
      "observedAt": "2026-10-27T14:02:11Z",
      "method": "sampled"
    },
    {
      "advertiser": {
        "name": "RentRival",
        "hostname": "rentrival.example"
      },
      "venue": "linkedin",
      "format": "text",
      "headline": "Renewal notices, sent on time, every time",
      "body": "For property managers with 50 to 500 doors.",
      "cta": "Book a demo",
      "landingUrl": "https://rentrival.example/renewals",
      "mediaUrl": null,
      "firstSeen": "2026-10-08",
      "lastSeen": "2026-10-26",
      "daysRunning": 18,
      "transparencyUrl": null,
      "observedAt": "2026-10-27T14:02:11Z",
      "method": "sampled"
    }
  ],
  "total": 37,
  "after": "ad_k2Lw",
  "cost": {
    "usd": 0,
    "maxUsd": 0.0036,
    "units": 2,
    "misses": 0
  }
}
```

## Verbs
| Verb | The question it answers | Price | Success rate |
| --- | --- | --- | --- |
| [`Ad.find`](/code/data/ads/find) | Which ads are my rivals paying to keep running? | 0.2¢ a search | 99.9% of 309,000 calls |

## The order you call them in
1. [`Ad.find`](/code/data/ads/find): Which ads are my rivals paying to keep running?

## Monitors on this Noun
| Verb | What it watches |
| --- | --- |
| [`Ad.find`](/code/data/ads/find) | A rival starts a new ad on any site, weekly. |

## Works with
- **Workflows:** [Competitor gap](/capabilities/size-up-competitors/competitor-gap) · [Pick who to sell to first](/capabilities/find-customers/pick-who-to-sell-to)