Search ads with a POST body

Try in Playground

Retrieve one public page with the documented filters and an opaque continuation cursor. Lowercase /adlibrary/ aliases return canonical Post/Author data.

POST/v1/facebook/adLibrary/search/adsx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Content-Typestringrequiredheader

Must be application/json.

Request body

querystringrequiredbody

Keyword or advertiser name.

min 1 chars · max 4096 chars

Examplerunning

search_typeenumdefault: "keyword_unordered"body

keyword_unordered (default) or keyword_exact_phrase.

one of: keyword_unordered, keyword_exact_phrase · default: "keyword_unordered"

ad_typeenumdefault: "all"body

all (default) or political_and_issue_ads.

one of: all, political_and_issue_ads · default: "all"

countrystringdefault: "ALL"body

Two uppercase letters or ALL. Defaults to ALL.

default: "ALL"

statusenumdefault: "ACTIVE"body

Query filter: ACTIVE (default), INACTIVE or ALL. Response: success, partial, failed or challenged.

one of: ALL, ACTIVE, INACTIVE · default: "ACTIVE"

media_typeenumdefault: "ALL"body

ALL (default), IMAGE, VIDEO, MEME, IMAGE_AND_MEME or NONE.

one of: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE · default: "ALL"

sort_byenumdefault: "total_impressions"body

total_impressions (default) or relevancy_monthly_grouped.

one of: total_impressions, relevancy_monthly_grouped · default: "total_impressions"

languagestringbody

Optional two-letter content language.

start_datestringbody

Optional real calendar date YYYY-MM-DD.

end_datestringbody

Optional real calendar date YYYY-MM-DD, on or after start_date.

trimenumbody

Use the compact field projection while preserving creative snapshots and regional transparency.

one of: true, false

cursorstringbody

Opaque continuation token bound to the operation and filters. POST supports long cursor values.

min 1 chars · max 65536 chars

Response fields

successboolean

Whether usable public data was retrieved.

statusenum

Query filter: ACTIVE (default), INACTIVE or ALL. Response: success, partial, failed or challenged.

one of: success, partial

requestIdstring

Request correlation ID.

sourceUrlstring

Canonical public library URL.

absolute HTTPS URL

fetchedAtstring

UTC retrieval time.

Completeness of the bounded source result, with explicit auxiliary-data warnings.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

Upstream requests, decoded response bytes and elapsed milliseconds. Page 1 includes browser bootstrap traffic; a warm continuation is one GraphQL POST.

accounting.upstreamRequestsinteger

Always included.

0 – 100

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

Source ad records with exact archive/page IDs, public creative snapshots, cards, images/videos, publisher platforms, dates and available counts. Unknown source values remain null.

up to 100 items

ads.ad_archive_idstring

Always included.

ads.page_idstring

Always included.

ads.is_activeboolean

Always included.

ads.snapshotobject

Always included.

Source ad records for keyword searches; advertiser suggestions for company search. ads is also retained as a service alias.

up to 100 items

searchResults.ad_archive_idstring

Always included.

searchResults.page_idstring

Always included.

searchResults.is_activeboolean

Always included.

searchResults.snapshotobject

Always included.

cursorstringnullable

Opaque continuation token bound to the operation and filters. POST supports long cursor values.

searchResultsCountnumbernullable

Source total estimate when available, otherwise null.

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
400	`invalid_request`	Invalid, conflicting or unsupported parameters/cursor.
401	`unauthorized`	Missing or invalid x-api-key.
403	`restricted_page`	Source marks the ad restricted.
404	`not_found`	Explicitly absent ad or no exact company match.
429	`upstream_rate_limited`	Meta rate limit after at most two fresh proxy-session retries; direct egress is never retried on the same IP.
502	`upstream_error` `upstream_challenged` `unsupported_page`	Source failed, challenged, or returned unsupported data.
502	`response_too_large` `request_limit` `payload_too_complex`	An operation bound was exceeded.
503	`busy`	Both retrieval slots are occupied.
504	`timeout`	The operation deadline expired.
503	`transcription_unavailable`	Local speech runtime is not configured.
502	`transcription_failed`	Media decoding or speech recognition failed.
422	`transcription_too_long`	Video exceeds the 180-second speech limit.

Code example

curl -X POST "https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running"}'

const response = await fetch(
  "https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "query": "running"
    })
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "query": "running"
    })
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`Meta Ads Library request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.post(
    "https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "query": "running"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"query":"running"}`)
	req, _ := http.NewRequest("POST", "https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/facebook/adLibrary/search/ads"))
            .POST(HttpRequest.BodyPublishers.ofString("{\"query\":\"running\"}"))
            .header("Content-Type", "application/json")
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Synthetic example validated against the runtime contract.

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://www.facebook.com/ads/library/",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_browser",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 24,
    "responseBytes": 11000000,
    "durationMs": 2800
  },
  "ads": [
    {
      "ad_archive_id": "123456789012345678",
      "page_id": "99887766",
      "is_active": true,
      "page_name": "Synthetic advertiser",
      "snapshot": {
        "body": {
          "text": "Synthetic ad copy"
        },
        "cards": [
          {
            "title": "Creative variant",
            "link_url": "https://example.com"
          }
        ],
        "images": [],
        "videos": []
      }
    }
  ],
  "cursor": null,
  "searchResultsCount": 1,
  "searchResults": [
    {
      "ad_archive_id": "123456789012345678",
      "page_id": "99887766",
      "is_active": true,
      "page_name": "Synthetic advertiser",
      "snapshot": {
        "body": {
          "text": "Synthetic ad copy"
        },
        "cards": [
          {
            "title": "Creative variant",
            "link_url": "https://example.com"
          }
        ],
        "images": [],
        "videos": []
      }
    }
  ]
}

Invalid, conflicting or unsupported parameters/cursor.

{
  "success": false,
  "status": "failed",
  "requestId": "string",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0
  },
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}