Walk compact company ads

Try in Playground

Retrieve a page of advertiser archive records as a normalized ads array with compact records and continuation.

POST/v1/facebook/ad-library/companies/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

pageIdstringbody

Exact numeric advertiser page ID. Use pageId or companyName.

Example99887766

companyNamestringbody

Unique case-insensitive advertiser name. Prefer pageId.

min 1 chars · max 4096 chars

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 smaller field projection before normalization.

one of: true, false

cursorstringbody

Opaque continuation token from data.page.nextCursor. POST supports long 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 warnings.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

Upstream requests, decoded response bytes and elapsed milliseconds.

accounting.upstreamRequestsinteger

Always included.

0 – 100

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

Compact archive result with one ads array and page state.

data.lookupStatusstring

Always included.

data.querystringoptional

Optional.

data.pageIdstringoptional

Optional.

data.companyNamestringoptional

Optional.

Always included.

up to 100 items

data.ads.idstring

Always included.

data.ads.adIdstringnullable

Always included.

data.ads.urlstring

Always included.

absolute HTTPS URL

Always included.

data.ads.page.idstringnullable

Always included.

data.ads.page.namestringnullable

Always included.

data.ads.page.urlstringnullable

Always included.

data.ads.page.isDeletedbooleannullable

Always included.

data.ads.page.profilePictureUrlstringnullable

Always included.

data.ads.page.likeCountnumbernullable

Always included.

data.ads.page.categoriesJSON[]

Always included.

data.ads.campaign.collationIdstringnullable

Always included.

data.ads.campaign.collationCountnumbernullable

Always included.

data.ads.isActivebooleannullable

Always included.

data.ads.publisherPlatformsJSON[]

Always included.

data.ads.startedAtstringnullable

Always included.

data.ads.endedAtstringnullable

Always included.

data.ads.categoriesJSON[]

Always included.

data.ads.countriesJSON[]

Always included.

data.ads.impressions.textstringnullable

Always included.

data.ads.impressions.indexnumbernullable

Always included.

data.ads.spend.amountstringnullable

Always included.

data.ads.spend.currencystringnullable

Always included.

data.ads.creative.bodyTextstringnullable

Always included.

data.ads.creative.titlestringnullable

Always included.

data.ads.creative.captionstringnullable

Always included.

data.ads.creative.linkUrlstringnullable

Always included.

data.ads.creative.linkDescriptionstringnullable

Always included.

data.ads.creative.callToActionstringnullable

Always included.

data.ads.creative.callToActionTypestringnullable

Always included.

data.ads.creative.displayFormatstringnullable

Always included.

data.ads.creative.images.urlstringnullable

Always included.

data.ads.creative.images.resizedUrlstringnullable

Always included.

data.ads.creative.images.watermarkedResizedUrlstringnullable

Always included.

data.ads.creative.videos.hdUrlstringnullable

Always included.

data.ads.creative.videos.sdUrlstringnullable

Always included.

data.ads.creative.videos.previewImageUrlstringnullable

Always included.

data.ads.creative.cards.titlestringnullable

Always included.

data.ads.creative.cards.bodystringnullable

Always included.

data.ads.creative.cards.captionstringnullable

Always included.

data.ads.creative.cards.linkUrlstringnullable

Always included.

data.ads.creative.cards.imageUrlstringnullable

Always included.

data.ads.creative.cards.videoUrlstringnullable

Always included.

data.page.nextCursorstringnullable

Always included.

data.page.hasMoreboolean

Always included.

data.page.totalResultsEstimatenumbernullable

Always included.

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/ad-library/companies/ads" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pageId":"99887766"}'

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

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/ad-library/companies/ads",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "pageId": "99887766"
    })
  }
);

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/ad-library/companies/ads",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "pageId": "99887766"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

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

func main() {
	body := strings.NewReader(`{"pageId":"99887766"}`)
	req, _ := http.NewRequest("POST", "https://api.scrapeatlas.com/v1/facebook/ad-library/companies/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/ad-library/companies/ads"))
            .POST(HttpRequest.BodyPublishers.ofString("{\"pageId\":\"99887766\"}"))
            .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-12T00:00:00.000Z",
  "coverage": {
    "source": "public_browser",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 41000,
    "durationMs": 1800
  },
  "data": {
    "lookupStatus": "found",
    "pageId": "99887766",
    "ads": [],
    "page": {
      "nextCursor": null,
      "hasMore": false,
      "totalResultsEstimate": 0
    }
  }
}

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