---
title: gads_list_ad_group_ads
description: Read the ads of one Google Ads account from Google Ads now, with the status of each.
---

Ask which ads of a Google Ads ad group run now. Google Ads calls an ad in an ad group an "ad group ad", and this tool uses that word.

> List the ads of the waterproof boots ad group on Google Ads.

The agent calls `gads_list_ad_group_ads` with the id of the ad group. You see each ad with its status. [Read your accounts](/mcp/tools/read-your-accounts) shows the full job.

## Reference

**Available on:** [![Google Ads](/providers/gads.svg)](https://docs.adcrunch.dev/connect/providers)

Google Ads: list the ad group ads of one ad account, as Google Ads holds them now. Each call asks Google Ads now, and it counts against the rate limits of Google Ads. AdCrunch stores nothing from this read. To read one, send its id in `ids`. `createdAt`, `updatedAt` and `deletedAt` are null on each row, because AdCrunch stored nothing. For a read across ad accounts, or of what AdCrunch stores, call `list_ads`. The answer holds at most `limit` rows (default 100, maximum 500). When it carries `nextCursor`, more rows exist: call this tool again with the same arguments and `cursor` set to that value. When it carries no `nextCursor`, you have every row.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `advertiserId` | string | yes | The Google Ads ad account to read, prefixed `acc_`. It must belong to the active organization. Find it with `list_advertisers`. |
| `ids` | array of (string, at least 1 character), at least 1 item | no | Read only the ad group ads with these ids: the value that each row answers as `id`. To read one, send one id. |
| `status` | one of `ACTIVE`, `PAUSED`, `DELETED`, `ARCHIVED` | no | Read only the entities that are set to this status, not the entities that deliver. Each row of the answer carries this status. Google Ads takes each status. A status that Google Ads never uses answers an empty list. |
| `cursor` | string, at least 1 character | no | The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor. |
| `limit` | integer, 1 to 500 | no | The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`. |
| `campaignId` | string | no | Read only the ad group ads of this campaign: the `campaignId` that each row answers. |
| `adGroupId` | string | no | Read only the ad group ads of this ad group: the `adGroupId` that each row answers. |

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `adGroupAds` | array of object | yes | The ad group ads of the ad account, as Google Ads holds them now, in the order of Google Ads. An empty array can carry `nextCursor`: then more rows can exist. |
| `adGroupAds[].advertiserId` | string | yes | The advertiser that owns it, prefixed `acc_`. |
| `adGroupAds[].createdAt` | number or null | yes | When AdCrunch first stored this row. **Null when the row was read live**: AdCrunch holds no copy of it. `createdAt`, `updatedAt` and `deletedAt` are AdCrunch’s own times, so all three are null together on a live row. |
| `adGroupAds[].createdTime` | number or null | yes | When the provider created the entity. This is the provider’s own time, so a live row carries it. Null where the provider reports none. |
| `adGroupAds[].currency` | string or null | yes | The account currency, ISO 4217. Every row of one advertiser carries the same one. Null when AdCrunch does not know it yet. |
| `adGroupAds[].deletedAt` | number or null | yes | When AdCrunch marked the row deleted. A listing never carries a deleted row, so this is null. |
| `adGroupAds[].id` | string | yes | The id the provider gives, with no prefix. It is unique for one provider and one type, and it may legitimately recur across two types or two providers. |
| `adGroupAds[].name` | string | yes | The name at the provider. |
| `adGroupAds[].path` | string | yes | The ancestors and this entity, ids joined by `/`, oldest first. This is what makes a subtree one string comparison. |
| `adGroupAds[].provider` | string | yes | The ad platform: `meta`, `tiktok` or `gads`. Those three are the providers whose entities AdCrunch reads, and https://docs.adcrunch.dev/connect/providers says how deep each one goes. |
| `adGroupAds[].status` | one of `ACTIVE`, `PAUSED`, `DELETED`, `ARCHIVED` | yes | The status, normalized across the providers. TikTok `ENABLE` and `DISABLE` read here as `ACTIVE` and `PAUSED`. |
| `adGroupAds[].updatedAt` | number or null | yes | When AdCrunch last rewrote this row. Null if it never changed. |
| `adGroupAds[].updatedTime` | number or null | yes | When the provider last edited the entity. Null where the provider reports none. |
| `adGroupAds[].adGroupId` | string or null | yes | The ad group that holds the ad, as the bare id its provider gives. Null only when the stored path of the row names no ad group. |
| `adGroupAds[].campaignId` | string or null | yes | The campaign it belongs to, as the bare id its provider gives. Null only when the stored path of the row names no campaign. |
| `adGroupAds[].type` | string | yes | The type the provider uses, kept as the provider writes it: `ad` at Meta and TikTok, and `ad_group_ad` at Google Ads. The resource names the concept, and the row keeps the provider’s own word, because a Meta `adset` and a Google Ads `ad_group` are not the same object. |
| `nextCursor` | string | no | Send this value as `cursor` to get the next page. It is absent on the last page. |

### Failure codes

A failed call has `isError` set, and `structuredContent.error` holds one of these codes. [Errors](/mcp/errors) describes the shape of a failed call.

- `not_found`
- `provider_not_connected`
- `provider_error`
- `live_read_unsupported`
- `invalid_cursor`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

The token must hold `observe:read`. [Auth & scopes](/mcp/auth) lists each scope.

### Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

- **Read-only.** The tool changes nothing.
- **Open world.** The tool reaches a system outside AdCrunch, such as an ad platform.

### Example

The arguments:

```json
{
  "advertiserId": "acc_4829301756",
  "ids": [
    "169283746152~712398456012"
  ]
}
```

The result, in `structuredContent`:

```json
{
  "adGroupAds": [
    {
      "adGroupId": "169283746152",
      "advertiserId": "acc_4829301756",
      "campaignId": "20481523697",
      "createdAt": null,
      "createdTime": null,
      "currency": "EUR",
      "deletedAt": null,
      "id": "169283746152~712398456012",
      "name": "Responsive search ad — winter",
      "path": "20481523697/169283746152/169283746152~712398456012",
      "provider": "gads",
      "status": "ACTIVE",
      "type": "ad_group_ad",
      "updatedAt": null,
      "updatedTime": null
    }
  ]
}
```