Build with AdScrape.

The AdScrape API gives you programmatic access to the same Meta Ad Library data as the dashboard: search, brand comparison, single-ad lookups, structured marketing analysis, usage telemetry, and billing. Every call returns JSON with consistent envelopes — there are no XML or form-encoded responses.

• REST + JSON

  UTF-8 JSON in/out. Errors share the same envelope as success responses.
• One key, all surfaces

  Same key works from the dashboard, n8n, Zapier, your backend, or a notebook.
• Per-key analytics

  Every call is logged with endpoint, status, latency, and credits spent.
• Pay per ad — from $0.05

  Scrape rate: $0.05/ad base, $0.04 on Growth, $0.03 on Scale. Media $0.10/ad, brand suggestions $0.01/suggestion.
• BYO proxy — skip $0.025/ad

  Plug in your own scraping proxy and pay the base rate. Without it, the managed pool adds $0.025/ad (≈ 2× credits).
• Media downloads

  Stream creatives through our CDN proxy without dealing with Meta hot-link rules.

1. 1

   Create a key.

   Sign in, then Settings → API Keys → Create. Copy the sk_live_… once — you won't see it again.

2. 2

   (Optional) Add your scraping proxy.

   Settings → Proxy drops the $0.025/ad managed-pool add-on. Skip if you'd rather pay the add-on and not run infra.

3. 3

   Fire your first search.

   Returns ranked ads + a session_token you can drain page-by-page.

curl -X POST https://api.adscrape.in/api/v1/search \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","max_results":25,"country":"US"}'

Every billable endpoint requires a key in the X-API-Key header. Keys are scoped per user and can be revoked at any time from Settings → API Keys. Treat them like passwords — anything that calls AdScrape with your key spends your credits.

curl -X POST https://api.adscrape.in/api/v1/search \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","max_results":25}'

AdScrape bills in credits backed by a transparent USD rate. New accounts get 10 free credits; topping up is per-credit, no monthly minimums. Every charge lands in your ledger at Settings → Billing. Reads from your own data are always free.

Worked example. A search for {"query":"nike","max_results":50} that returns 47 ads costs:

• 47 credits ≈ $2.35 on Starter with your own proxy (47 × $0.05 × 1.0).
• On managed pool ≈ $3.53 on Starter (47 × ($0.05 + $0.025)).
• On Growth + BYO proxy ≈ $1.88 (47 × $0.04).
• 0 credits if the page returned zero ads — you only pay for delivered results.

Your balance ticks down on success and is restored by top-ups, monthly plan grants, or manual ledger adjustments. There are five surfaces for working with it:

• Live balance

  GET /api/v1/billing/credits/status returns current balance and rolling burn over the requested window.
• Append-only ledger

  GET /api/v1/billing/credits exposes every delta with reason, ref_type, and ref_id — safe to mirror to a warehouse.
• Plans via Paddle · legacy Stripe

  GET /api/v1/config includes paddle_billing_configured / paddle_credit_addon_configured. POST /api/v1/billing/checkout returns a hosted Paddle or Stripe checkout URL depending on server configuration.
• Subscription grants

  Plans add a fixed monthly grant. Inspect via GET /api/v1/billing/subscription.
• Failure refunds

  A 5xx mid-request never debits you — credits are only charged after the response is successfully streamed. Partial pages bill for actual rows delivered.
• Free reads

  Anything that returns data already in your account — /ads/{id}, brand lookups, usage, billing — is permanently free.

curl https://api.adscrape.in/api/v1/billing/credits/status \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Meta rate-limits aggressively by IP. To make the API reliable, AdScrape maintains a residential-grade managed proxy pool and adds $0.025 / ad (≈ 2× credits) to scrape-driven calls when you use it. Plug in your own proxy to drop back to the base rate.

Multipliers apply to scrape-driven endpoints only — /search, /search/next, /suggestions (on cache miss), /compare, and /media/{id}. Pure-read endpoints over your own data are free in either mode.

curl -X PUT https://api.adscrape.in/api/v1/proxy \
  -H "Authorization: Bearer YOUR_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"proxy_url":"http://user:pass@proxy.example.com:8080"}'

Each API key inherits the rate limit of its owner's active subscription. Limits are applied per minute, per key, using a sliding-window counter in Redis (with an in-process fallback if Redis is unavailable). When a request would exceed the limit, the API returns 429 Too Many Requests with a Retry-After header and your client should back off.

We also globally throttle scraping concurrency upstream of Meta so a single noisy customer cannot starve everyone else. If our pool is briefly saturated you'll see 502 Bad Gateway — treat the same as 429 and back off.

from tenacity import retry, stop_after_attempt, wait_exponential_jitter
from httpx import HTTPStatusError

@retry(
    stop=stop_after_attempt(5),
    wait=wait_exponential_jitter(initial=2, max=30),
    retry=lambda e: isinstance(e, HTTPStatusError) and e.response.status_code in (429, 502, 503),
)
def search(client, body):
    r = client.post("/api/v1/search", json=body, timeout=60)
    r.raise_for_status()
    return r.json()

Your current limit is shown at Settings → Billing and via GET /api/v1/billing/subscription.

A few hard limits keep the API stable for everyone. These are enforced server-side and can't be opted-out of without a custom plan.

• Search page size

  max_results on /search is capped at 500. page_size on /search/next is also capped at 500. Use cursor pagination to walk past 500 in one session.
• Compare width

  Between 2 and 4 brands per call. max_results_per_brand caps at 200.
• Suggestions limit

  limit is between 1 and 50. Cache TTL is 1 hour.
• Media downloads

  Single creative per call (up to 80 MB). We only proxy Meta CDN hosts — *.fbcdn.net, *.facebook.com, *.cdninstagram.com and *.instagram.com. Other URLs are refused with 403.
• Concurrency per key

  Up to 8 concurrent requests per API key against scrape-driven endpoints. Excess requests queue briefly and may return 429 if the wait exceeds 30 s.
• Country coverage

  We mirror Meta's coverage. political_and_issue_ads data is unavailable in jurisdictions where Meta itself does not publish it.
• Personal-data fields

  The Meta Ad Library does not expose user-level demographic data. The API never invents it; fields are null when missing.
• Key revocation

  Revoked keys return 401 immediately. There is no grace period. Sessions opened with a revoked key are invalidated on next call.

The AdScrape API ships data sourced from the Meta Ad Library, which is itself a public transparency tool. Your use of the API must comply with the policy below in addition to Meta's own Ad Library terms.

• Permitted use

  Market research, creative inspiration, competitive analysis, journalism, academic research, political ad transparency reporting, internal dashboards and product integrations.
• Prohibited use

  Re-identification of individuals from public ad records, building a paid mirror that undercuts Meta's policy obligations, training models that produce defamatory or deceptive political content, automated harassment, or any use that violates Meta's TOS.
• Attribution

  When you display ad creatives publicly, credit "Meta Ad Library" as the source. AdScrape attribution is appreciated but not required.
• Storage & retention

  You may cache responses indefinitely for internal product use. If you republish creatives, honor any takedown signals from Meta within 72 hours.
• Sharing keys

  API keys are personal to the issuing user. Sharing a key with a team is fine; reselling access or routing third-party customers through a single key is not — use plans+keys per customer instead.
• Abuse & throttling

  We reserve the right to revoke keys, lower rate limits, or block IP ranges that send traffic patterns indicating automated abuse (e.g. credential stuffing, DDoS, scraping our frontend instead of the API). You'll receive an email before any non-emergency action.
• Compliance escalation

  Concerns about content surfaced through the API — copyright, defamation, election integrity — should be reported to abuse@adscrape.in. We forward to Meta where appropriate.

Errors share one shape: { "detail": string | object }. For credit errors, detail is an object so you can inspect the balance.

{
  "detail": {
    "error": "INSUFFICIENT_CREDITS",
    "balance": 12,
    "required": 100
  }
}

• 400
  Bad Request

  Your payload failed validation. The response body explains which field.
• 401
  Unauthorized

  Missing or invalid API key, or a revoked key.
• 402
  Payment Required

  Insufficient credits. Detail includes balance and required. Top up.
• 404
  Not Found

  Resource doesn't exist or isn't visible to you (e.g. another user's key).
• 429
  Too Many Requests

  Rate limit exceeded. Honor the Retry-After header before retrying.
• 500
  Server Error

  Unexpected failure on our side. Safe to retry with exponential backoff.
• 502
  Bad Gateway

  Upstream Meta API returned an error. Retry with backoff (start at 2s).
• 503
  Service Unavailable

  Optional feature isn't configured (e.g. local LLM analysis without Ollama).

Meta CDN URLs are short-lived, signed, and frequently reject hot-linked browser requests. This endpoint streams the bytes server-side so you can persist creatives without dealing with referrer / CORS edge-cases. Bytes are not cached on our side — every request is a fresh pull from Meta.

curl -L -o ad.jpg "https://api.adscrape.in/api/v1/media/933016365009192?kind=image&index=0" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Every billable call is logged with status, latency, and credits spent. The same data drives the in-app dashboards at Settings → Usage and Settings → Billing, so you can build the same views externally.

{
  "days": 30,
  "total_requests": 1241,
  "total_credits": 9824,
  "avg_duration_ms": 412.7,
  "by_endpoint": [
    { "endpoint": "/api/v1/search", "requests": 800, "credits": 8000 },
    { "endpoint": "/api/v1/suggestions", "requests": 410, "credits": 1024 }
  ]
}

{
  "balance": 4200,
  "credits_used": 842,
  "credits_pending": 5000,
  "period_days": 30,
  "renewal_at": "2026-06-01T12:00:00+00:00"
}

These endpoints back Settings → API Keys. They require a session cookie or another active API key (you can't bootstrap a key from zero — sign in via the dashboard first).

[
  {
    "id": "key_01HZ…",
    "name": "Production server",
    "prefix": "sk_live_…abcd",
    "is_active": true,
    "last_used_at": "2026-05-10T18:11:22+00:00",
    "created_at": "2025-12-01T08:00:00+00:00"
  }
]

{
  "id": "key_01HZ…",
  "name": "Production server",
  "full_key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "sk_live_…abcd",
  "created_at": "2025-12-01T08:00:00+00:00"
}

Manage the BYO scraping proxy attached to your account. These endpoints require a session JWT (Authorization: Bearer …) — they cannot be called with an API key, because rotating the proxy that powers your API key should never be allowed from inside your own automation.

{
  "configured": true,
  "masked_host": "pr***le:8080",
  "scheme": "http",
  "cost_multiplier": 1.0,
  "note": "Direct routing via your proxy — base credit rate applied."
}

curl -X PUT https://api.adscrape.in/api/v1/proxy \
  -H "Authorization: Bearer YOUR_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"proxy_url":"socks5h://user:pass@proxy.example.com:1080"}'