# Search advertisers

Returns advertisers matching `query`. Optionally filter by `country`, choose ordering, set the report type, and continue with `page_token`.

- Platform: Google Ads
- Request: `GET https://api.toolzerhub.com/v1/google-ads/advertisers/search`
- Auth: `x-api-key` header
- Cost: 1 credit per successful request. Failed requests are not billed.
- Page: https://docs.toolzerhub.com/reference/google-ads/advertisers/google-ads-search-advertisers

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `query` | query | yes | string | Free-text advertiser name search. |
| `country` | query | no | string | Two-letter ISO-3166 country code to narrow advertiser search results. |
| `num_results` | query | no | integer | Page size, 1-100. Default: 20. |
| `page_token` | query | no | string | Opaque cursor from a previous response's next_page_token. Omit for the first page. |
| `sort_key` | query | no | enum: unknown, revenue, name, creative_count, impressions | unknown keeps Google's default relevance ordering. Default: unknown. |
| `descending` | query | no | boolean |  Default: true. |
| `report_type` | query | no | enum: all, political | all covers every advertiser/creative; political scopes to Google's separate election-ads transparency report. Default: all. |

## Example request

```bash
curl "https://api.toolzerhub.com/v1/google-ads/advertisers/search?query=<query>" \
  -H "x-api-key: $TOOLZERHUB_API_KEY"
```

Success responses are wrapped as `{ "data": ... }`. Errors return `{ "error": { "code", "status", "message", "retryable", "details" } }`. See https://docs.toolzerhub.com/docs/responses-and-errors.