# Search ads across ad libraries

Searches the public Meta, Google, TikTok, and LinkedIn ad libraries in one call and returns ads in a shared shape. Requires `query`; `platforms` and `countries` narrow the search, and `limit` caps total ads. `sources[]` reports each library's result.

- Platform: Ad Library
- Request: `GET https://api.toolzerhub.com/v1/ad-library/search`
- Auth: `x-api-key` header
- Cost: 4 credits per successful request. Failed requests are not billed.
- Page: https://docs.toolzerhub.com/reference/ad-library/search-ad-libraries

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `query` | query | yes | string | Brand, advertiser, or keyword. Every library supports advertiser-name search; Google resolves the name to an advertiser first, because its creative search cannot take free text. |
| `platforms` | query | no | string | Comma-separated ad libraries to query. Defaults to all four. Narrow this to avoid paying for sources you don't need. Default: meta,google,tiktok,linkedin. |
| `countries` | query | no | string | Comma-separated ISO 3166-1 alpha-2 codes. Meta, Google, and TikTok accept one country per query and use the first entry; LinkedIn accepts the full list. UK is corrected to GB and EL to GR, because those are the codes people write and neither is the ISO code the libraries answer to. Default: US. |
| `date_min` | query | no | string | Earliest ad-activity date (YYYY-MM-DD). When omitted, TikTok falls back to the last 90 days because it requires a window. |
| `date_max` | query | no | string | Latest ad-activity date (YYYY-MM-DD). Defaults to today. |
| `active_status` | query | no | enum: all, active, inactive | Delivery status. Only Meta filters on this; the other libraries ignore it and report whatever status they expose. Default: all. |
| `media_type` | query | no | enum: all, image, video | Creative format filter. Applied by Meta and Google when searching; applied to the merged results afterward for TikTok and LinkedIn. Default: all. |
| `limit` | query | no | integer | Maximum ads across every library combined. Results are interleaved round-robin so one library cannot crowd out the rest. Default: 40. |
| `enrich_details` | query | no | string | Include available advertiser, date, and copy details for LinkedIn ads. Disable for a faster, lower-cost response with fewer fields. Default: true. |
| `include_source` | query | no | string | Include each ad's original platform record in source when you need fields outside the shared response shape. Default: false. |

## Example request

```bash
curl "https://api.toolzerhub.com/v1/ad-library/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.