Ad Library Ad

GET/v1/facebook/adLibrary/adNot available

Returns a single ad from the Facebook Ad Library, optionally with a transcript of its video. Not available yet.

Not available

This route is documented so that existing integrations get a clear answer, but it returns no data: every call is a free error and costs no credits. The notes below say what it answers.

01Query parameters

Name	Type	Description
idoptional	string	The Ad Library ad id. One of `id` or `url` is required.
urloptional	string	An Ad Library ad URL, e.g. `https://www.facebook.com/ads/library?id=1702938977100376`. One of `id` or `url` is required.
get_transcriptoptional	boolean	Set to `true` to add a transcript of the ad's video.Default: `false`
allow_long_transcriptionoptional	boolean	Set to `true` to transcribe a video longer than 120 seconds with AI, at 10 credits per started minute. Only the literal value `true` opts in.Default: `false`
trimoptional	boolean	Set to `true` for a shorter response.Default: `false`

02Responses

Real answers from the API. Lists are shortened to 2 items.

GET /v1/facebook/adLibrary/ad

{
  "success": false,
  "credits_remaining": 4980,
  "credits_charged": 0,
  "error": "missing_parameter",
  "errorStatus": 400,
  "message": "You must provide an 'id' or 'url'"
}

Common to every endpoint

Any route can answer these: a missing or wrong key, no credits left, the platform not answering, or a failure on our side. None of them costs credits.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

03Notes

The Facebook Ad Library is not available through this API yet: a call with its required parameters answers a 503 `upstream_unavailable` and is free. Missing required parameters still return a free 400.

04Errors & credits

Every error has success: false, a real HTTP status and costs no credits.

400missing_parameter
A required parameter is missing or invalid.
403private_account
The account is private or age-restricted.
404not_found
No such account.
503upstream_error
The platform did not answer; retry shortly.