---
search:
  tags:
    - Stored reads
    - GET
seo:
  description: >-
    Available on: Meta TikTok Google Ads OpenAI. Reference for the GET
    /observe/ad-groups endpoint in the AdCrunch API.
sidebar:
  label: List ad groups
  badge: GET
title: List ad groups
type: openapi-operation
---
**Available on:** [![Meta](/providers/meta.svg)](https://docs.adcrunch.dev/connect/providers) [![TikTok](/providers/tiktok.svg)](https://docs.adcrunch.dev/connect/providers) [![Google Ads](/providers/gads.svg)](https://docs.adcrunch.dev/connect/providers) [![OpenAI](/providers/openai.svg)](https://docs.adcrunch.dev/connect/providers)

Stored read. Lists the ad groups of every ad account your organization connects, across the providers, newest first.

### One concept, three words

An ad group is a Meta **ad set**, a TikTok **ad group** and a Google Ads **ad group**. This path reads all three at once, and every row keeps the word its own provider writes, in `type`. AdCrunch renames nothing: a Meta `adset` and a Google `ad_group` are not the same object, and a caller that must speak to the provider needs the provider’s word.

### Narrowing

Send `campaignId` to read one campaign’s ad groups, and `provider` to read one platform. `limit` counts rows of the answer itself, not rows of each advertiser. When the answer holds `nextCursor`, more rows exist: send it back as `cursor` to get the next page.

### Budget

An ad group that carries its own budget answers it in `budget`, in **whole units** of its `currency`, and a `budgetLevel` of `ad_group`. One whose campaign carries the budget answers a null `budget` and a `budgetLevel` of `campaign`: read the campaign for the amount. Every Google Ads ad group is the second kind, because Google Ads keeps every budget on the campaign.

### What is not here

Performance Max campaigns have **no ad groups**. Google’s automation delivers them through an asset group instead, which is a child of the campaign and a sibling of an ad group — so a Performance Max campaign answers nothing here, and that is not a fault. Read `/observe/asset-groups` for those.

`GET /observe/ad-groups`

**Responses**

- `200` — The matching ad groups, and how many there are in all. Each row keeps its provider’s own \`type\`: \`adset\`, \`adgroup\` or \`ad\_group\`.
- `400` — The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. \`error\` is \`invalid\_request\`, and \`issues\` names each field. Nothing was changed. Or AdCrunch cannot use the \`cursor\`: it cannot read it, or the cursor belongs to a different query. Then \`error\` is \`invalid\_cursor\`. Send the \`nextCursor\` of the previous page with no change, or omit \`cursor\` to get the first page.
- `401` — No API key, or one that does not resolve. See the security scheme. \`error\` is \`unauthorized\`.
- `402` — The organization has no active subscription. An owner subscribes at \`paywallUrl\`. \`error\` is \`organization\_unentitled\`.
- `403` — The caller does not hold \`observe:read\`. \`error\` is \`forbidden\`.

Response example, 200:

```json
{
  "data": [
    {
      "advertiserId": "acc_1203456789012345",
      "bidAmount": null,
      "bidStrategy": null,
      "budget": null,
      "budgetLevel": "campaign",
      "budgetType": null,
      "campaignId": "120210000000000",
      "createdAt": 1789610000000,
      "createdTime": 1789600000000,
      "currency": "EUR",
      "deletedAt": null,
      "endTime": null,
      "id": "120210000000001",
      "name": "Women 25-44, France",
      "path": "120210000000000/120210000000001",
      "provider": "meta",
      "roasFloor": null,
      "startTime": null,
      "status": "ACTIVE",
      "type": "adset",
      "updatedAt": null,
      "updatedTime": 1789900000000
    }
  ],
  "nextCursor": "eyJwIjpbMTc4OTYxMDAwMDAwMCwibWV0YSIsImFkc2V0IiwiMTIwMjEwMDAwMDAwMDAxIl0sInEiOiI1bHgzc2UzOTBpIn0"
}
```
