Get company ads

Try in Playground

Retrieve public advertiser suggestions or one page of an advertiser’s ads. Company-name lookup requires a unique exact match; use pageId when ambiguous.

GET/v1/facebook/adLibrary/company/adsx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

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

Query parameters

pageIdstringquery

Exact numeric advertiser page ID. Use pageId or companyName.

Example99887766

companyNamestringquery

Requires exactly one case-insensitive exact advertiser-name match. Prefer pageId to avoid ambiguity.

min 1 chars · max 4096 chars

countrystringdefault: "ALL"query

Two uppercase letters or ALL. Defaults to ALL.

default: "ALL"

statusenumdefault: "ACTIVE"query

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

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

media_typeenumdefault: "ALL"query

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

total_impressions (default) or relevancy_monthly_grouped.

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

languagestringquery

Optional two-letter content language.

start_datestringquery

Optional real calendar date YYYY-MM-DD.

end_datestringquery

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

trimenumquery

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

one of: true, false

cursorstringquery

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

Company ad records. ads remains a service alias.

up to 100 items

results.ad_archive_idstring

Always included.

results.page_idstring

Always included.

results.is_activeboolean

Always included.

results.snapshotobject

Always included.

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 "https://api.scrapeatlas.com/v1/facebook/adLibrary/company/ads?pageId=99887766" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.scrapeatlas.com/v1/facebook/adLibrary/company/ads?pageId=99887766",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

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/company/ads?pageId=99887766",
  {
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!
    }
  }
);

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.get(
    "https://api.scrapeatlas.com/v1/facebook/adLibrary/company/ads",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "pageId": "99887766"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.scrapeatlas.com/v1/facebook/adLibrary/company/ads?pageId=99887766", nil)
	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/company/ads?pageId=99887766"))
            .GET()
            .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": []
      }
    }
  ],
  "results": [
    {
      "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."
  }
}