Agents

curl -X POST https://api.publicadsapi.com/v1/agent/signup \
  -H "content-type: application/json" \
  -d '{"name": "Claude Code for Example Ltd", "use_case": "Weekly report of competitor ads on Meta and Google"}'

{
  "api_key": "pads_test_EXAMPLEKEY",
  "mode": "test",
  "name": "Claude Code for Example Ltd",
  "use_case": "Weekly report of competitor ads on Meta and Google",
  "claim_url": "https://publicadsapi.com/claim#EXAMPLE",
  "next_steps": "This is a sandbox key: it returns sample ads, never calls a platform, costs nothing and does not expire. …"
}

curl -X POST https://api.publicadsapi.com/v1/agent/live-key \
  -H "authorization: Bearer $PADS_API_KEY"

# Public Ads API

> An API for the public ad libraries: the Meta Ad Library, the Google Ads Transparency Center, the TikTok Commercial Content Library and the LinkedIn Ad Library. One endpoint per platform, `GET https://api.publicadsapi.com/v1/meta/ads`, `GET https://api.publicadsapi.com/v1/google/ads`, `GET https://api.publicadsapi.com/v1/tiktok/ads`, `GET https://api.publicadsapi.com/v1/linkedin/ads`, each with that library's own filters, returns the same JSON `Ad` record; `GET https://api.publicadsapi.com/v1/ads/{id}` returns one ad with all its detail. Free plan: 100 credits a month.

Last updated: 2026-10-21

Auth: `Authorization: Bearer <key>`. Keys starting `pads_test_` return sample ads and are free; `pads_live_` keys read the platform. Sign up at https://publicadsapi.com/signup. An agent without a key can get a sandbox key itself with `POST https://api.publicadsapi.com/v1/agent/signup` (no auth; `{"name": "...", "use_case": "..."}`), then a live key with free credits with `POST https://api.publicadsapi.com/v1/agent/live-key`.

## Facts

- A page of ads or one ad uses 1 credit (LinkedIn 2). An empty page, an error and every sandbox call use none.
- Free: 100 credits a month, no card. Starter is $19 a month for 8,000 credits; Growth $49 for 25,000. Extra credits $0.0025 each.
- Each platform takes only its own filters; any other parameter is `400 INVALID_INPUT` with `field` naming it.
- Google has no keyword search: search by advertiser id or domain. TikTok covers the EEA, the UK and Switzerland only. LinkedIn covers the last 12 months.
- A live call takes 2 to 15 seconds: set a 60 second timeout. Media URLs are the platforms' own and expire.
- Public Ads API is not affiliated with Meta, Google, TikTok or LinkedIn.

## Get started

- [Overview](https://publicadsapi.com/docs.md): Search the public ad libraries of Meta, Google, TikTok and LinkedIn with one API key.
- [Quickstart](https://publicadsapi.com/docs/quickstart.md): Search an ad library with a sandbox key, read the next page with next_cursor, test your error handling, then switch to a live key.
- [Authentication and keys](https://publicadsapi.com/docs/authentication.md): Every request sends an API key as a bearer token.

## API reference

- [Search overview](https://publicadsapi.com/docs/api/search.md): Each platform has its own search endpoint, which takes only the filters that platform's library has.
- [Meta](https://publicadsapi.com/docs/api/meta.md): Search Facebook, Instagram, Messenger, Audience Network and Threads ads in the Meta Ad Library by keyword or by advertiser, with Meta's own filters: country, active status, media, placements, category, language and sort.
- [Google](https://publicadsapi.com/docs/api/google.md): Search one advertiser's ads in the Google Ads Transparency Center (Search, YouTube, Shopping, Maps and Play) by its advertiser id or verified domain, filtered by country, format, surface and political ads.
- [TikTok](https://publicadsapi.com/docs/api/tiktok.md): Search ads in TikTok's Commercial Content Library by keyword or advertiser, in one country of the EEA, the UK or Switzerland, within a date window.
- [LinkedIn](https://publicadsapi.com/docs/api/linkedin.md): Search the LinkedIn Ad Library by keyword, company id or company name, filtered by the countries an ad was shown in and dates within the last year.
- [One ad](https://publicadsapi.com/docs/api/ads.md): The Ad record plus detail: every version of the ad, each country it ran in, targeting, the EU's reach figures (Meta) and who paid.
- [The Ad record](https://publicadsapi.com/docs/api/ad-record.md): Every platform's ads come back in one shape, with the same keys, ISO dates and ranges.
- [Errors](https://publicadsapi.com/docs/errors.md): Every error is { "error": { "code", "message" } } with a matching HTTP status.

## Usage and billing

- [Credits and billing](https://publicadsapi.com/docs/credits.md): A credit is one page of ads or one ad with its detail.
- [Rate limits](https://publicadsapi.com/docs/rate-limits.md): Each live key may send a number of requests a second, set by its plan.

## For agents

- [Agents](https://publicadsapi.com/docs/agents.md): An AI agent can get its own sandbox key, build and test against it, then get a live key with free credits, all without a person signing up.

## More

- [Changelog](https://publicadsapi.com/docs/changelog.md): Changes to the API, newest first.

## Machine-readable

- [OpenAPI 3.1 spec](https://publicadsapi.com/openapi.json): the full contract, one schema per platform's search
- [llms-full.txt](https://publicadsapi.com/llms-full.txt): the whole integration in one file

## Pages

- [Pricing](https://publicadsapi.com/pricing.md): plans, what a credit is, and what a month costs