Facebook Ad Library Search API examples for SocQ

Search public Facebook Ad Library ads by keyword and filters, returning advertiser, creative text, media, delivery, and visible metrics as normalized records.

Try Facebook Ad Library Search API · Get an API key · Documentation · All SocQ examples

Use cases

• Keyword-led ad discovery: Use the submitted query, ad IDs, creative text, advertiser names, and public URLs to assemble a traceable set of matching public ads.
• Creative and format comparison: Compare creative titles, body text, images, videos, display formats, CTA values, destinations, and publisher platforms across matched records.
• Active-ad monitoring: Repeat a defined query and compare ad IDs, active state, start and end times, publisher platforms, and collection times across observations.
• Advertiser candidate research: Use advertiser Page IDs, names, aliases, URLs, visible Page likes, and the matching creative to identify Pages for focused follow-up research.

API behavior

• query accepts one non-empty keyword or phrase; optional filters control matching, country, status, media, dates, and ordering.
• results_limit defaults to 100 and accepts integers from 20 through 2,000.
• Search rankings and public availability can change; retain extra.search_query and collected_at with each observation.
• Creative media, delivery dates, reach, spend, Page likes, CTA values, and destination fields are optional public values.

All requests use the shared asynchronous flow:

submit -> task_id -> poll task -> read every cursor page -> save results

Quick start

cp .env.example .env
export SOCQ_API_KEY="your-api-key"

Run the complete Node.js workflow:

cd node
npm start

Run the complete Python workflow:

python3 -m pip install -r python/requirements.txt
python3 python/main.py

Both examples load payload.example.json, retry transient API responses, wait for task completion, read every cursor page, and save a paginated public ad dataset with advertiser, creative, delivery, and visible-metric context to output/results.json.

Never expose SOCQ_API_KEY in browser code, mobile apps, public repositories, screenshots, fixtures, or logs.

Request

POST https://api.socq.ai/v1/facebook-ad-library/search
Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/json

{
  "query": "running shoes",
  "results_limit": 100,
  "country": "US",
  "status": "ACTIVE",
  "media_type": "VIDEO"
}

The submit response contains data.task_id. Poll the task endpoint until data.status becomes succeeded or failed, then continue with data.results.next_cursor while data.results.has_more is true.

Complete workflow example

The Node.js and Python programs implement the production-shaped happy path:

1. Load and validate configuration.
2. Submit the endpoint-specific payload.
3. Retry rate-pressure and transient server responses with bounded backoff.
4. Poll the asynchronous task with a ten-minute application timeout.
5. Stop cleanly on a failed task and surface the public error message.
6. Read all cursor pages instead of silently returning only the first page.
7. Write a stable JSON artifact containing task metadata and normalized records.

Use the synthetic files in fixtures/ for tests and documentation. They do not contain customer, account, or production data.

Production notes

See docs/production-notes.md for validation, retry, timeout, pagination, deduplication, logging, and endpoint-specific guidance.

Responsible use and platform scope

• Use only publicly accessible Facebook Ad Library ads, advertiser Pages, creative content, delivery context, and visible signals supported by the selected endpoint.
• Do not use the examples to access restricted content, login-only surfaces, authentication controls, or non-public information about advertisers or audiences.
• SocQ is not an official API of the represented social platform and is not affiliated with or endorsed by that platform.
• Before production use, assess the laws, platform terms, privacy obligations, and retention requirements that apply to your organization and use case.
• Collect only the fields needed for a defined purpose, restrict access, set retention periods, and support correction or deletion workflows where required.
• Platform names and trademarks belong to their respective owners.

This section describes the public-data boundary; it is not legal advice or a guarantee that every use case is permitted in every jurisdiction.

Repository contents

Path	Purpose
curl/request.md	Copy-paste submit, poll, and pagination requests
node/index.mjs	Complete Node.js workflow
python/main.py	Complete Python workflow
payload.example.json	Safe endpoint-specific request body
fixtures/	Synthetic submit and task response shapes
docs/production-notes.md	Production integration guidance