---
search:
  tags:
    - Stored reads
    - GET
seo:
  description: >-
    Available on: Meta TikTok Google Ads OpenAI. Reference for the GET
    /observe/ads endpoint in the AdCrunch API.
sidebar:
  label: List ads
  badge: GET
title: List ads
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 ads of every ad account your organization connects, across the providers, newest first.

### One concept, two words

An ad is an `ad` at Meta and TikTok. At Google Ads it is an **`ad_group_ad`** — the link resource that joins an ad to an ad group, whose id is the composite `{adGroupId}~{adId}`. AdCrunch stores that link as the leaf and does not model a separate shared ad, so a Google row answers the composite id. Every row keeps its own provider’s word in `type`.

### Narrowing

Two parents, and they are not the same question. `adGroupId` reads the ads of one ad group. `campaignId` reads **every** ad of a campaign, whatever ad group holds it — a grandparent, which the ad group filter cannot express. Send both to narrow twice.

### What is not here

Performance Max campaigns have **no ads**. Google’s automation assembles placements from an asset group, so nothing below a Performance Max campaign appears here.

`GET /observe/ads`

**Responses**

- `200` — The matching ads, and how many there are in all. Each row keeps its provider’s own \`type\`: \`ad\`, or \`ad\_group\_ad\` at Google Ads.
- `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": [
    {
      "adGroupId": "169283746152",
      "advertiserId": "acc_4829301756",
      "campaignId": "20481523697",
      "createdAt": 1789610000000,
      "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
    }
  ],
  "nextCursor": "eyJwIjpbMTc4OTYxMDAwMDAwMCwiZ2FkcyIsImFkX2dyb3VwX2FkIiwiMTY5MjgzNzQ2MTUyfjcxMjM5ODQ1NjAxMiJdLCJxIjoiZTBmZ2hvbDFrYSJ9"
}
```
