API v1
Build with public ad data.
A JSON API for bounded Meta Ad Library collection. Every task is tenant-isolated, quota-aware, observable, and safe to retry.
Quickstart
curl -X POST https://your-domain.example/v1/tasks \
-H 'Authorization: Bearer fb_live_your_key' \
-H 'Idempotency-Key: my-first-run' \
-d '{"q":"running shoes","country":"US","count":100}'Authentication
Generate a key in the dashboard and send it as Authorization: Bearer <api-key>. The full secret is shown once.
Idempotency
Retry task creation with the same Idempotency-Key to receive the original task without double-reserving quota.
Endpoints
POST
Create a collection task
/v1/tasksCreate a collection task
POST
Create from a Meta URL
/v1/tasks/from_urlCreate from a Meta URL
GET
Poll task state
/v1/tasks/{uuid}/statusPoll task state
GET
Read paginated ads
/v1/tasks/{uuid}/resultsRead paginated ads
GET
Search observed ads
/v1/archive/adsSearch observed ads
POST
Create a signed webhook
/v1/webhooksCreate a signed webhook
POST
Create a recurring run
/v1/schedulesCreate a recurring run
Limits & errors
Quota exhaustion returns 402. Rate limiting returns 429 with Retry-After. Collection coverage is observational, not exhaustive.