# Public Ads API

> Search the public ad libraries of Meta, Google, TikTok and LinkedIn with one API key. Each platform has its own endpoint with its own filters, and every one answers with the same `Ad` record. Start in the sandbox, free, then go live.

Base URL: `https://api.publicadsapi.com` · Auth: `authorization: Bearer <key>` · Web version: https://publicadsapi.com/docs

- [Quickstart](https://publicadsapi.com/docs/quickstart.md): Your first search in a minute, with a sandbox key.
- [Search a platform](https://publicadsapi.com/docs/api/search.md): GET /v1/{platform}/ads: each platform and the filters its library has.
- [For AI agents](https://publicadsapi.com/docs/agents.md): An agent can get its own key, test it and go live with no person signing up.

- **Credits**: 1 credit a page or ad. LinkedIn 2. Empty pages, errors and every sandbox call are free.
- **Free plan**: 100 credits a month. No card. Then a plan, or a card for extra credits.
- **Machine-readable**: OpenAPI 3.1. At [/openapi.json](https://publicadsapi.com/openapi.json), with one schema per platform. Every page also as Markdown.

## The four libraries

| Endpoint | Library | Search by | Ads a page | Credits | Covers |
| --- | --- | --- | --- | --- | --- |
| [GET /v1/meta/ads](https://publicadsapi.com/docs/api/meta.md) | Meta Ad Library | `q` or `page_id` | up to 30 | 1 | Every country Meta runs ads in |
| [GET /v1/google/ads](https://publicadsapi.com/docs/api/google.md) | Google Ads Transparency Center | `advertiser_id` or `domain` | up to 100 | 1 | Every country Google runs ads in |
| [GET /v1/tiktok/ads](https://publicadsapi.com/docs/api/tiktok.md) | TikTok Commercial Content Library | `q` or `advertiser` | up to 36 | 1 | The EEA, the UK and Switzerland |
| [GET /v1/linkedin/ads](https://publicadsapi.com/docs/api/linkedin.md) | LinkedIn Ad Library | `q`, `company_id` or `company` | about 24 | 2 | Every country, the last 12 months |

`GET https://api.publicadsapi.com/v1/ads/{id}` returns one ad from any of them with all its detail: every version of the ad, each country it ran in, targeting, the EU's reach figures and who paid. See [One ad](https://publicadsapi.com/docs/api/ads.md).

## Conventions

- Base URL `https://api.publicadsapi.com`. Every request sends `Authorization: Bearer <key>`: see [Authentication and keys](https://publicadsapi.com/docs/authentication.md).
- JSON in UTF-8. Dates and times are ISO 8601 in UTC. Lists are arrays.
- What a platform does not have is `null`, never a missing key, so every ad has the same keys whichever library it came from.
- Every error is `{ "error": { "code", "message" } }` with an HTTP status to match. Switch on `code`: see [Errors](https://publicadsapi.com/docs/errors.md).
- Every call that can use credits says how many it used and how many are left, in the body and in `X-Credits-*` headers.
- Public Ads API is not affiliated with Meta, Google, TikTok or LinkedIn. It reads their public ad libraries.

> **Reading this as an LLM or agent?** Start at [/llms.txt](https://publicadsapi.com/llms.txt) or [/llms-full.txt](https://publicadsapi.com/llms-full.txt), or add `.md` to any docs address for plain Markdown. The contract is [/openapi.json](https://publicadsapi.com/openapi.json).

See also: [Quickstart](https://publicadsapi.com/docs/quickstart.md)