Collect one public Facebook Ad Library ad from its ad URL, returning creative text, advertiser context, media, delivery timing, and visible signals as a normalized record.
Try Facebook Ad Library Ad API · Get an API key · Documentation · All SocQ examples
- Enrich a selected ad: Use the archive ID, advertiser identity, creative title, body text, media, CTA, destination URL, and input URL to complete an existing ad record.
- Review creative assets and destinations: Inspect deduplicated image or video references together with display format, CTA text, CTA type, and the public destination link for a known ad.
- Review public delivery context: Use active status, start and end times, publisher platforms, country values, and available reach or spend fields to examine the public delivery context.
- Preserve point-in-time ad snapshots: Store creative, advertiser, delivery, visible signal, input URL, and collected_at fields for later comparison of the same known ad.
- Submit one public Facebook Ad Library URL whose
/ads/libraryquery contains a numericidvalue. - One task accepts one URL and can produce at most one normalized ad record.
- A valid but unavailable, removed, or restricted ad can complete without a result record.
- 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
cp .env.example .env
export SOCQ_API_KEY="your-api-key"Run the complete Node.js workflow:
cd node
npm startRun the complete Python workflow:
python3 -m pip install -r python/requirements.txt
python3 python/main.pyBoth examples load payload.example.json, retry transient API responses, wait
for task completion, read every cursor page, and save an enriched public ad record with creative, advertiser, media, delivery, and visible-signal details to
output/results.json.
Never expose SOCQ_API_KEY in browser code, mobile apps, public repositories,
screenshots, fixtures, or logs.
POST https://api.socq.ai/v1/facebook-ad-library/ad
Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/json{
"url": "https://www.facebook.com/ads/library/?id=1000000000000000"
}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.
The Node.js and Python programs implement the production-shaped happy path:
- Load and validate configuration.
- Submit the endpoint-specific payload.
- Retry rate-pressure and transient server responses with bounded backoff.
- Poll the asynchronous task with a ten-minute application timeout.
- Stop cleanly on a failed task and surface the public error message.
- Read all cursor pages instead of silently returning only the first page.
- 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.
See docs/production-notes.md for validation,
retry, timeout, pagination, deduplication, logging, and endpoint-specific
guidance.
- 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.
| 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 |