---
title: "Search the public Ad Library"
method: GET
path: "/v1/messaging/ads/library"
tags: ["Ad Library"]
---

# Search the public Ad Library

`GET /v1/messaging/ads/library`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/ads/library`
- Auth: HTTP bearer

Searches Meta's or LinkedIn's public Ad Library to see what ads other advertisers run, for competitor and market research.

Meta's Ad Library
(`GET /ads_archive`) is searched with Zernio's own developer access, so `platform=meta` needs
no connected account at all. LinkedIn's Ad Library (`GET /rest/adLibrary`) runs on a connected
`linkedin` / `linkedinads` account, passed as `accountId`. Passing a Meta account as `accountId`
also selects Meta. Rows are returned in the platform's raw shape under `data`; `paging.after`
is an opaque cursor on both (`null` when exhausted).

**Meta coverage.** Political and social-issue ads are searchable worldwide. Every other ad is
in the archive only if it was delivered to the EU or UK within the last year, so a US-only
commercial advertiser is invisible. Spend, impressions and demographics are political-only
fields and are left out of the default projection; request them via `fields`. All customers
share Zernio's Meta quota, so a `429` means back off for a minute.

**LinkedIn coverage.** Ads served after June 1 2023, worldwide, kept for a year after their
last impression. EU-delivered ads carry impression ranges and the disclosed targeting facets.
Pages are capped at 25 ads (`limit` > 25 is a 400); `after` is the next offset.

Which params apply: `q`, `countries`, `limit`, `after` on both; `pageIds`, `adType`, `status`,
`platforms`, `mediaType`, `languages`, `searchType`, `fields`, `since`, `until` are Meta-only;
`advertiser` is LinkedIn-only. Passing a param the account's platform does not support is a 400
naming the param.


**Billing:** Read (free unless it says otherwise) · **Rate limit:** 120/min

## Query parameters

- `q` string: Keyword search. Meta does not translate it, so write it in the ads' language. Required unless pageIds (Meta) or advertiser (LinkedIn) is given.
- `after` string: paging.after of the previous page.
- `limit` integer: Rows per page. LinkedIn accepts at most 25.
- `since` string, date: Meta only. Earliest delivery date (YYYY-MM-DD). LinkedIn's archive does not filter by date, so it is a 400 there: filter on details.adStatistics.firstImpressionAt / latestImpressionAt instead (EU-delivered ads only).
- `until` string, date: Meta only. Latest delivery date (YYYY-MM-DD); a 400 on LinkedIn, see since.
- `adType` 'ALL' | 'POLITICAL_AND_ISSUE_ADS' | 'HOUSING_ADS' | 'EMPLOYMENT_ADS' | 'FINANCIAL_PRODUCTS_AND_SERVICES_ADS': Meta only.
- `fields` string: Meta only. Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently.
- `status` 'ACTIVE' | 'INACTIVE' | 'ALL': Meta only. ACTIVE = eligible for delivery right now.
- `pageIds` string: Meta only. Comma-separated Facebook Page ids (max 10) whose ads to list.
- `platform` 'meta' | 'linkedin': Which archive to search. `meta` needs no accountId. Required unless accountId is given.
- `accountId` string: Zernio SocialAccount id. Required for LinkedIn (linkedin / linkedinads: its token searches). Optional for Meta, where any facebook / instagram / metaads account only selects the platform.
- `countries` string: Comma-separated ISO 3166-1 alpha-2 codes the ads reached. Meta defaults to ALL (an explicit ALL is Meta-only); LinkedIn searches every market when omitted.
- `languages` string: Meta only. Comma-separated ISO 639-1 codes of the ad text.
- `mediaType` 'ALL' | 'IMAGE' | 'MEME' | 'VIDEO' | 'NONE': Meta only.
- `platforms` string: Meta only. Comma-separated publisher platforms: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, WHATSAPP, OCULUS, THREADS, STREAMING_SERVICES.
- `advertiser` string: LinkedIn only. Advertiser (Page) name to search.
- `searchType` 'KEYWORD_UNORDERED' | 'KEYWORD_EXACT_PHRASE': Meta only. Whether q matches words in any order or as an exact phrase (comma-separate phrases to match all of them).

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `data` object[], required
    - `paging` object, required
      - `after` string, nullable: Cursor for the next page; null when exhausted.
      - `total` integer: LinkedIn only. Total matching ads.
    - `platform` 'meta' | 'linkedin', required
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)