# Google Ads Ads (`google-ads.ads`)

Lists the ads of a Google Ads account with type, final URLs, responsive search ad headlines, status, policy approval and clicks, cost and conversions for a date range.

Docs: https://primaryapi.com/docs/api-reference/google-ads/ads

- Endpoint: `POST https://api.primaryapi.com/v1/run/google-ads.ads`
- Category: Search & SEO · Platform: `google-ads` · Kind: list · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=google-ads.ads`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `customerId` | string | yes |  | pattern: ^(\d{3})-?(\d{3})-?(\d{4})$ | Google Ads customer (account) id, 10 digits with or without hyphens, e.g. "123-456-7890". List yours with google-ads.accounts. |
| `dateRange` | enum | no | "LAST_30_DAYS" | one of: TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_BUSINESS_WEEK, THIS_MONTH, LAST_MONTH, THIS_WEEK_SUN_TODAY, THIS_WEEK_MON_TODAY, LAST_WEEK_SUN_SAT, LAST_WEEK_MON_SUN | Period of the metrics, in the account’s time zone (default LAST_30_DAYS). Ignored when startDate/endDate are set. |
| `startDate` | string | no |  | pattern: ^\d{4}-\d{2}-\d{2}$ | Custom period start (YYYY-MM-DD), with endDate. |
| `endDate` | string | no |  | pattern: ^\d{4}-\d{2}-\d{2}$ | Custom period end (YYYY-MM-DD), inclusive, with startDate. |
| `limit` | integer | no | 50 | 1–1000 | Maximum number of results to return (1-1000, default 50). |
| `statuses` | enum[] | no | ["ENABLED","PAUSED"] | min 1 items; max 3 items | Ad statuses to include (default ENABLED and PAUSED). |
| `campaignId` | string | no |  | pattern: ^\d{1,20}$ | Only the ads of this campaign (numeric id). |
| `adGroupId` | string | no |  | pattern: ^\d{1,20}$ | Only the ads of this ad group (numeric id). |
| `cursor` | string | no |  |  | Opaque pagination cursor: pass the previous response's nextCursor. |
| `loginCustomerId` | string | no |  | pattern: ^(\d{3})-?(\d{3})-?(\d{4})$ | Only when the connected Google account reaches `customerId` THROUGH a manager (MCC) account: that manager account’s id (10 digits). Sent as the login-customer-id header. Omit for accounts the Google account can open directly. |
| `connection` | string | no |  | max 200 chars | Which connected account to use when the workspace has several for this provider: the customId you gave it (exact), its connection id ("con_…"), its handle (login, email or @handle) or its name. Optional; prefer the customId or id, which never match two accounts. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `customerId` | string |  |
| `currencyCode` | string \| null |  |
| `period` | string | The GAQL date condition used, e.g. "DURING LAST_30_DAYS" |
| `nextCursor` | string \| null |  |
| `ads` | object[] |  |
| `ads[].id` | string |  |
| `ads[].resourceName` | string | The ad group ad, customers/{customerId}/adGroupAds/{adGroupId}~{adId} |
| `ads[].name` | string \| null |  |
| `ads[].type` | string \| null | RESPONSIVE_SEARCH_AD, RESPONSIVE_DISPLAY_AD, VIDEO_RESPONSIVE_AD, … |
| `ads[].status` | string \| null | ENABLED, PAUSED or REMOVED |
| `ads[].primaryStatus` | string \| null | ELIGIBLE, PAUSED, REMOVED, PENDING, LIMITED or NOT_ELIGIBLE |
| `ads[].adStrength` | string \| null | PENDING, NO_ADS, POOR, AVERAGE, GOOD or EXCELLENT |
| `ads[].finalUrls` | string[] |  |
| `ads[].headlines` | object[] \| null | Responsive search ads only |
| `ads[].headlines[].text` | string \| null |  |
| `ads[].headlines[].pinnedField` | string \| null | HEADLINE_1, HEADLINE_2, DESCRIPTION_1, …; null when not pinned |
| `ads[].descriptions` | object[] \| null | Responsive search ads only |
| `ads[].descriptions[].text` | string \| null |  |
| `ads[].descriptions[].pinnedField` | string \| null | HEADLINE_1, HEADLINE_2, DESCRIPTION_1, …; null when not pinned |
| `ads[].path1` | string \| null |  |
| `ads[].path2` | string \| null |  |
| `ads[].policy` | object |  |
| `ads[].policy.approvalStatus` | string \| null | APPROVED, APPROVED_LIMITED, AREA_OF_INTEREST_ONLY or DISAPPROVED |
| `ads[].policy.reviewStatus` | string \| null | REVIEW_IN_PROGRESS, REVIEWED, UNDER_APPEAL or ELIGIBLE_MAY_SERVE |
| `ads[].policy.topics` | object[] | Policy findings, e.g. { topic: "TRADEMARKS_IN_AD_TEXT", type: "LIMITED" } |
| `ads[].policy.topics[].topic` | string \| null |  |
| `ads[].policy.topics[].type` | string \| null |  |
| `ads[].adGroup` | object |  |
| `ads[].adGroup.id` | string \| null |  |
| `ads[].adGroup.name` | string \| null |  |
| `ads[].campaign` | object |  |
| `ads[].campaign.id` | string \| null |  |
| `ads[].campaign.name` | string \| null |  |
| `ads[].metrics` | object |  |
| `ads[].metrics.impressions` | integer \| null |  |
| `ads[].metrics.clicks` | integer \| null |  |
| `ads[].metrics.cost` | number \| null | In the account currency |
| `ads[].metrics.costMicros` | integer \| null |  |
| `ads[].metrics.conversions` | number \| null |  |
| `ads[].metrics.conversionsValue` | number \| null |  |
| `ads[].metrics.ctr` | number \| null |  |
| `ads[].metrics.averageCpc` | number \| null | cost ÷ clicks, in the account currency |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

Pagination: pass the previous response’s `nextCursor` as `cursor` to get the next page; `nextCursor: null` means there are no more results.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/google-ads.ads" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"1234567890"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "customerId": "1234567890",
      "currencyCode": "USD",
      "period": "DURING LAST_30_DAYS",
      "ads": [
        {
          "id": "4441",
          "resourceName": "customers/1234567890/adGroupAds/2221~4441",
          "name": null,
          "type": "RESPONSIVE_SEARCH_AD",
          "status": "ENABLED",
          "primaryStatus": "ELIGIBLE",
          "adStrength": "GOOD",
          "finalUrls": [
            "https://www.example.com/"
          ],
          "headlines": [
            {
              "text": "Example Store",
              "pinnedField": "HEADLINE_1"
            },
            {
              "text": "Free Shipping Over $50",
              "pinnedField": null
            }
          ],
          "descriptions": [
            {
              "text": "Shop the full range online.",
              "pinnedField": null
            }
          ],
          "path1": "shop",
          "path2": null,
          "policy": {
            "approvalStatus": "APPROVED_LIMITED",
            "reviewStatus": "REVIEWED",
            "topics": [
              {
                "topic": "TRADEMARKS_IN_AD_TEXT",
                "type": "LIMITED"
              }
            ]
          },
          "adGroup": {
            "id": "2221",
            "name": "Brand terms"
          },
          "campaign": {
            "id": "111",
            "name": "Brand - Search"
          },
          "metrics": {
            "impressions": 3900,
            "clicks": 310,
            "cost": 155,
            "costMicros": 155000000,
            "conversions": 15,
            "conversionsValue": 1650,
            "ctr": 0.0794872,
            "averageCpc": 0.5
          }
        }
      ],
      "nextCursor": null
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z",
  "nextCursor": null
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=google-ads.ads`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Runs as your connected Google account and needs the Google Ads capability (ads). headlines, descriptions and paths are filled for responsive search ads; other ad types return their type, final URLs, status and policy. policy.topics lists Google’s policy findings without the evidence text. Amounts are in the account currency (currencyCode). Sorted by cost, highest first. Narrow with campaignId or adGroupId.

