Build with AdScrape.

The AdScrape API gives you programmatic access to the same Meta Ad Library data as the dashboard: search, single-ad lookups, media downloads, competitor trackers, usage, 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 use

  Search bills 1 credit per ad delivered. Suggestions per result block. Media downloads per file. Tracker slots are a separate subscription — see Credit model.
• Media downloads

  Download or hotlink stored creatives via stable URLs — no Meta hot-link headaches in your app.

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

   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, where 1 credit = 1 ad returned from search. Every paid plan includes a monthly credit allotment, and new accounts get 10 free credits. Top up anytime with credit packs — 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 — one credit per delivered ad (47 ads × 1 credit).
• 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 Razorpay

  GET /api/v1/config includes razorpay_configured. POST /api/v1/billing/create-order opens Standard Checkout; POST /api/v1/billing/verify-payment confirms the signature and grants credits or activates the plan.
• 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"

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.
• Suggestions limit

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

  One creative per GET /api/v1/media/{archive_id} call (up to 80 MB). The download proxy only streams Meta CDN hosts (*.fbcdn.net, *.facebook.com, *.cdninstagram.com, *.instagram.com). Other origins return 403. In-app previews use stored /media/static/ URLs when available.
• 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. enrichment models not installed on the API).

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"

Search bills per ad (credits). Trackers use separate brand and keyword slot pools on paid plans (Pro and Enterprise include weekly reports; Starter is search-only). Manage trackers in Trackers; set the digest email via PATCH /api/v1/trackers/preferences. Sample reports: /reports/demo.

{
  "id": "…",
  "page_id": "15087023444",
  "page_name": "Nike",
  "country": "ALL",
  "page_profile": {
    "page_name": "Nike",
    "facebook": { "handle": "@nike", "followers": 39600000, "verified": true },
    "instagram": { "username": "@nike", "followers": 292000000, "verified": true },
    "page_history": { "merged_pages_count": 0, "name_changes_count": 1, "created_at": "2008-05-21T…" },
    "organization": { "name": "NIKE, Inc.", "address": "Beaverton, OR, United States" },
    "admin_locations": [{ "country": "United States", "count": 98 }],
    "meta_ad_library_url": "https://www.facebook.com/ads/library/?…&view_all_page_id=15087023444",
    "ads_indexed": false
  },
  "last_snapshot_at": null,
  "created_at": "2026-05-29T12:00:00+00:00"
}

Every billable call is logged with status, latency, and credits spent. The in-app view lives on the Dashboard (overview + quick actions at the top, full analytics under #usage). Legacy /settings/usage redirects there. Credits and plans are also on Billing. Mirror the same JSON from the endpoints below.

{
  "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"
}

Admin API

Requires is_admin (users whose email is in ADMIN_EMAILS are promoted on login). Powers Admin → Users and Admin → Analytics.

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"
}