# Google Ads Transparency API guide



## Choose a Google Ads Transparency operation



Start with the object your task needs. The groups below use the current catalogue; open an endpoint to check accepted identifiers, filters, price and availability before retrieving.



### Other operations



- [Ad details](https://www.monocrawl.com/docs/endpoints/google_ads/ad) — One Google ad creative: impression band, regions shown, and the creative variations (headline, description, destination).

- [Company ads](https://www.monocrawl.com/docs/endpoints/google_ads/company-ads) — Ads a company runs across Google surfaces: creative ids, formats and transparency-page links. Listing mode by design — drill into one ad with google_ads/ad. Paged by cursor.



### Search and discovery



- [Advertiser search](https://www.monocrawl.com/docs/endpoints/google_ads/search-advertisers) — Search Google Ads Transparency advertisers: verified advertiser ids, names and regions. The advertiser id feeds google_ads/company-ads.



## Check fields and collection limits



Use the endpoint’s declared parameters and returned continuation. Filters from another platform do not automatically apply here. Preserve source identifiers, URLs and warnings; a successful page does not establish complete history. Published response schemas identify whether they come from a reviewed shaper or observed response shapes.



Agents can use `get_endpoint` for the current contract and `get_docs` with topic `platforms/google_ads` to read this page. The [coverage guide](https://www.monocrawl.com/docs/data-availability) explains nulls and partial results, and the [production guide](https://www.monocrawl.com/docs/production-checklist) covers budgets and recovery.



## Endpoint reference

## google_ads/ad

`GET /v1/google_ads/ad`

One Google ad creative: impression band, regions shown, and the creative variations (headline, description, destination).

*Ad details*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | adstransparency.google.com creative URL from google_ads/company-ads. — e.g. `https://adstransparency.google.com/advertiser/AR02903092099014459393/creative/CR09470540953698697217` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/google_ads/ad?url=https%3A%2F%2Fadstransparency.google.com%2Fadvertiser%2FAR02903092099014459393%2Fcreative%2FCR09470540953698697217" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "ad_url": "https://example.com/example",
  "advertiser_id": "example",
  "creative_id": "example",
  "format": "example",
  "impressions": {},
  "last_shown": "example",
  "platform": "example",
  "regions": [
    "example"
  ],
  "variations": [
    {
      "description": "example",
      "destination_url": "https://example.com/example",
      "headline": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/google_ads/ad#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/google_ads/ad.json)


## google_ads/company-ads

`GET /v1/google_ads/company-ads`

Ads a company runs across Google surfaces: creative ids, formats and transparency-page links. Listing mode by design — drill into one ad with google_ads/ad. Paged by cursor.

*Company ads*

| Parameter | Required | Description |
| --- | --- | --- |
| `advertiser_id` | yes | Advertiser id from google_ads/search-advertisers (or pass domain instead). — e.g. `AR02903092099014459393` |
| `domain` | no | Company domain — alternative to advertiser_id. — e.g. `lululemon.com` |
| `region` | no | Two-letter region code. |
| `platform` | no | youtube, search, shopping, maps or play. Accepted values: youtube, search, shopping, maps, play. Case, spaces, hyphens and underscores are interchangeable. |
| `format` | no | text, image or video. Accepted values: text, image, video. Case, spaces, hyphens and underscores are interchangeable. |
| `topic` | no | Topic filter. |
| `start_date` | no | YYYY-MM-DD. |
| `end_date` | no | YYYY-MM-DD. |
| `cursor` | no | Opaque cursor from the previous page. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `region`: Select the documented source market or request location. Read this endpoint’s region semantics; it does not generally prove creator residence.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/google_ads/company-ads?advertiser_id=AR02903092099014459393" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "dropped": 0,
  "items": [
    {
      "ad_url": "https://example.com/example",
      "advertiser_id": "example",
      "advertiser_name": "example",
      "creative_id": "example",
      "first_shown": "example",
      "format": "example",
      "last_shown": "example",
      "platform": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/google_ads/company-ads#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/google_ads/company-ads.json)


## google_ads/search-advertisers

`GET /v1/google_ads/search-advertisers`

Search Google Ads Transparency advertisers: verified advertiser ids, names and regions. The advertiser id feeds google_ads/company-ads.

*Advertiser search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Advertiser or brand name. — e.g. `lululemon` |
| `region` | no | Two-letter region code. — e.g. `US` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `region`: Select the documented source market or request location. Read this endpoint’s region semantics; it does not generally prove creator residence.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/google_ads/search-advertisers?query=lululemon" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "advertiser_id": "example",
      "name": "example",
      "platform": "example",
      "region": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/google_ads/search-advertisers#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/google_ads/search-advertisers.json)