Get a Meta Ad (GET /v1/ads/meta/{library_id})

GET/v1/ads/meta/{library_id}

One Meta Ad by its Ad Library id, trimmed like a search result, with as_of (when it was last observed in the library). Served from our stored copy when observed under 6 hours ago; otherwise read live, stored, and given a Snapshot. An Ad Meta no longer shows is still served from our stored copy with removed_from_library: true, at the same price. An id that was never stored here and is not in the library is not_found (404) and nothing is charged. If the library cannot be reached the Run fails with source_unavailable and nothing is charged. analyze=true adds Ad analysis (the video set for a video Ad, the image set for an image or carousel Ad), computed once per Ad and version from our archived media with the ad copy as context; when it must be computed expect a 202 and poll the Run, and if it fails the Run fails and nothing is charged. analysis already stored rides along on every lookup, free.

Open in Playground(no API Key needed)

Price

3 credits, read live or from our stored copy (observed under 6 h ago, or removed from the library). With analyze=true, plus 20 credits, whether the analysis is computed or already stored.

Supports estimate=true: the reply is the price in Credits and whether it would be cached, with no Run created and nothing charged.

A cached result costs the same as a fresh one; cached says which you got.

Parameters

Name	In	Type	Required	Default	Description
`library_id`	path	`string`	Required	—	The Meta Ad Library id: the number in `facebook.com/ads/library/?id=...`.
`analyze`	query	`string`one of `true`, `false`	Optional	—	`true` to add Ad analysis: 20 credits, computed or already stored.
`wait`	query	`integer`min 0; max 120	Optional	`30`	Seconds to hold the response open before handing back a running Run to poll. Default 30, max 120. A POST may send it in the body instead; given in both places with different values it is a 400.
`estimate`	query	`boolean`	Optional	—	`true` returns `{ estimate_credits, cached }` computed from what is already stored, and creates no Run. Nothing is charged. When a source the call would read is unavailable and the answer is not served from cache, the estimate adds `unavailable`, the `{ platform, capability }` parts it cannot reach, or answers 503 `source_unavailable` when it can reach none. Only `true` or `false`; anything else is a 400. A POST may send it in the body instead; given in both places with different values it is a 400.
`Idempotency-Key`	header	`string`	Optional	—	1-255 printable ASCII characters. Replaying this key with the same payload returns the original Run (202 while it is still running); a different payload, or a different operation, is a 409 `idempotency_conflict`.

Responses

200 OK

The Run finished inside the wait budget: { run, result }. The example is an Ad Meta has removed, served from our stored copy at the same price as a live read.

any of 2 shapes

Option 1object
- runobjectrequiredEvery charged operation creates a Run. The envelope is identical whether the result came back inline or was polled.
  idstringrequired
  kindstringrequiredWhat was run, e.g. video_lookup.
  statusstringrequiredone of running, completed, partial, failedpartial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
  created_atstringrequiredRFC 3339.
  completed_atstringrequirednullableNull while the Run is still running.
  charge_creditsintegerrequiredWhat this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
  list_price_creditsintegerrequiredThe full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
  cachedbooleanrequiredTrue when a stored result answered without paying the vendor.
  progressobjectWhat a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
  stagestringrequiredone of keywords, searching, filtering, analysing, writing_digest
  keywordsintegervalue at least 0
  searchesintegervalue at least 0
  foundintegervalue at least 0
  judgedintegervalue at least 0
  keptintegervalue at least 0
  dropped_off_topicintegervalue at least 0
  dropped_unsureintegervalue at least 0
  shortlistedintegervalue at least 0
  analysedintegervalue at least 0
  updated_atstringrequired
- resultobjectrequired
  adobjectrequired
  librarystringrequiredone of meta, tiktok
  idstringrequired
  urlstringrequirednullable
  advertiserobjectrequired
  idstringrequirednullable
  namestringrequirednullable
  is_activebooleanrequirednullable
  first_shownstringrequirednullable
  last_shownstringrequirednullable
  placementsarray of stringrequired
  creativeobjectrequired
  titlestringrequirednullable
  bodystringrequirednullable
  ctastringrequirednullable
  link_urlstringrequirednullable
  formatstringrequirednullable
  image_urlsarray of stringrequired
  video_urlsarray of stringrequired
  thumbnail_urlsarray of stringrequired
  reachobjectrequiredRanges as the library reports them, never coerced. Meta discloses spend and impressions for political and issue Ads, and reach (audience) for some EU Ads; otherwise null.
  impressionsstringrequirednullable
  spendstringrequirednullable
  currencystringrequirednullable
  audiencestringrequirednullable
  kindstringnullableone of commercial, political, issueMeta only.
  media_typestringnullableone of video, image, carouselMeta only.
  countriesarray of stringnullableMeta only. Countries reached, when Meta discloses them.
  variant_countnumbernullableMeta only. How many Ads share this Ad's media; null for a single Ad.
  days_runningnumbernullableMeta only. Whole days from start to stop, or to now while running.
  archivedbooleanMeta only. True when every media URL is our permanent archived copy; false while any is still Meta's expiring URL (retried on the next sighting).
  winner_scoreobjectnullableMeta only. How strongly the Ad looks like a winner. 0 to 100, computed from the stored history of the Ad, never fetched. score = round(100 x (0.7 x rank(days_running) + 0.3 x rank(variants_added))), where rank is the share of the Advertiser's other Ads below this one (ties count half) and variants_added is the variant count at the latest Snapshot minus at the first. With one Snapshot the score is round(100 x rank(days_running)), confidence low, reason single_snapshot. With no other dated Ad of the Advertiser, rank falls back to min(days, 90)/90 and min(variants, 5)/5; under 5 dated Ads of the Advertiser the score is low confidence, reason few_advertiser_ads. No start date: score null, reason no_start_date.
  scorenumberrequirednullable
  confidencestringrequiredone of high, low
  inputsobjectrequired
  days_runningnumberrequirednullable
  variants_addednumberrequired
  snapshotsnumberrequired
  advertiser_adsnumberrequiredDated Ads of this Advertiser stored so far, this one included.
  reasonstringrequirednullableone of single_snapshot, few_advertiser_ads, no_start_date
  intelligenceany of 2 shapesnullableMeta only. Present when already computed for this Ad, or asked for with analyze; null under analyze when it could not be computed.
  Option 1objectVideo Ads: the full video analysis, read from the archived video with the ad copy as context.
  versionintegerrequired
  modelstringrequired
  computed_atstringrequired
  sourcestringrequired
  contentobjectrequired
  summarystringrequired
  nichestringrequired
  languagesarray of stringrequired
  content_stylesarray of stringrequired
  keywordsarray of objectrequired
  keywordstringrequired
  categorystringrequired
  sentimentnumberrequired
  transcriptstringrequirednullable
  hookobjectrequired
  opening_linestringrequirednullable
  typestringrequired
  visual_hookstringrequirednullable
  rationalestringrequirednullable
  persuasionobjectrequired
  call_to_actionobjectrequired
  typestringrequired
  textstringrequirednullable
  sponsoredbooleanrequired
  sponsorship_signalsarray of stringrequired
  brands_and_productsarray of objectrequired
  namestringrequired
  kindstringrequired
  prominencestringrequired
  trend_referencesarray of objectrequired
  namestringrequired
  kindstringrequired
  toneobjectrequired
  sentiment_labelstringrequired
  sentiment_scorenumberrequired
  primary_emotionstringrequired
  emotion_intensitynumberrequirednullable
  emotion_rationalestringrequirednullable
  speaking_stylestringrequired
  speaking_style_notesstringrequirednullable
  visualobjectrequired
  formatstringrequired
  settingstringrequired
  face_visibilitystringrequired
  on_screen_textarray of stringrequired
  has_on_screen_captionsbooleanrequired
  camera_notesstringrequirednullable
  lighting_notesstringrequirednullable
  elementsany
  safetyobjectrequired
  brand_safety_tierstringrequired
  reasonsarray of stringrequired
  notesstringrequirednullable
  pipelinestringrequiredalways video
  Option 2objectImage and carousel Ads: the analysis an image can carry, read from the archived images with the ad copy as context.
  pipelinestringrequiredalways image
  versionintegerrequired
  modelstringrequired
  computed_atstringrequired
  images_analyzedintegerrequired
  summarystringrequired
  copyobjectrequired
  anglestringrequired
  rationalestringrequirednullable
  headlinestringrequirednullable
  offerobjectrequired
  typestringrequired
  textstringrequirednullable
  call_to_actionobjectrequired
  typestringrequired
  textstringrequirednullable
  visualobjectrequired
  formatstringrequired
  on_image_textarray of stringrequired
  topicsarray of stringrequired
  toneobjectrequired
  sentiment_labelstringrequired
  sentiment_scorenumberrequired
  removed_from_librarybooleanrequiredTrue when Meta no longer shows the Ad and it was served from our stored copy.
  removed_atstringrequirednullableWhen this API first found the Ad gone from the library.
  as_ofstringrequirednullableWhen the Ad was last observed in Meta's library.
Option 2objectReturned instead of a Run when estimate=true. Nothing is charged. Operations with more to say about a quote add members; the two above are always present.
- estimate_creditsintegerrequiredWhat the call would be charged, in Credits.
- cachedbooleanrequiredWhether a stored result can already answer. It does not change the price.

200 · The Run finished inside the wait budget: `{ run, result }`. The example is an Ad Meta has removed, served from our stored copy at the same price as a live read.

{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "ad_lookup",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 3,
    "list_price_credits": 3,
    "cached": true
  },
  "result": {
    "ad": {
      "library": "meta",
      "id": "2233445566778899",
      "url": "https://www.facebook.com/ads/library/?id=2233445566778899",
      "advertiser": {
        "id": "100064000000001",
        "name": "Plunge"
      },
      "is_active": false,
      "first_shown": "2026-06-02T00:00:00.000Z",
      "last_shown": "2026-07-14T00:00:00.000Z",
      "placements": [
        "INSTAGRAM"
      ],
      "creative": {
        "title": "Three minutes. Every morning.",
        "body": "Our coldest tub yet, now in matte black.",
        "cta": "Learn More",
        "link_url": "https://plunge.example/black",
        "format": "IMAGE",
        "image_urls": [
          "https://scontent.xx.fbcdn.net/ads/plunge-black.jpg"
        ],
        "video_urls": [],
        "thumbnail_urls": []
      },
      "reach": {
        "impressions": null,
        "spend": null,
        "currency": null,
        "audience": null
      },
      "kind": "commercial",
      "media_type": "image",
      "countries": null,
      "variant_count": null,
      "days_running": 42,
      "winner_score": {
        "score": 54,
        "confidence": "low",
        "inputs": {
          "days_running": 42,
          "variants_added": 0,
          "snapshots": 1,
          "advertiser_ads": 14
        },
        "reason": "single_snapshot"
      },
      "removed_from_library": true,
      "removed_at": "2026-09-20T08:00:00.000Z"
    },
    "as_of": "2026-07-14T09:12:58.104Z"
  }
}

200 · With `estimate=true`: the price, no Run, no charge.

{
  "estimate_credits": 3,
  "cached": true,
  "priced_per": "ad_delivered"
}

202 Accepted

Still running: { run }. Poll GET /v1/runs/{id}.

object

Still running. Poll GET /v1/runs/{id}.

runobjectrequiredEvery charged operation creates a Run. The envelope is identical whether the result came back inline or was polled.
- idstringrequired
- kindstringrequiredWhat was run, e.g. video_lookup.
- statusstringrequiredone of running, completed, partial, failedpartial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
- created_atstringrequiredRFC 3339.
- completed_atstringrequirednullableNull while the Run is still running.
- charge_creditsintegerrequiredWhat this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
- list_price_creditsintegerrequiredThe full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
- cachedbooleanrequiredTrue when a stored result answered without paying the vendor.
- progressobjectWhat a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
  stagestringrequiredone of keywords, searching, filtering, analysing, writing_digest
  keywordsintegervalue at least 0
  searchesintegervalue at least 0
  foundintegervalue at least 0
  judgedintegervalue at least 0
  keptintegervalue at least 0
  dropped_off_topicintegervalue at least 0
  dropped_unsureintegervalue at least 0
  shortlistedintegervalue at least 0
  analysedintegervalue at least 0
  updated_atstringrequired

202 · Example

{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "ad_lookup",
    "status": "running",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": null,
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  }
}

400 Bad Request

invalid_request (a malformed id, wait, estimate or Idempotency-Key) or unsupported_platform, refused before any Run opens. Nothing is charged.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`estimate` must be `true` or `false`."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console."
}

402 Payment Required

insufficient_balance — the Balance cannot cover the quoted price (the worst case for Research and enriched search). No Run is created and nothing is charged. A multi-item Run whose Balance runs short later charges its completed items up to the Balance and ends partial.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

402 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance does not cover this operation. Top up in the console.",
  "balance_credits": 0,
  "required_credits": 3
}

409 Conflict

idempotency_conflict — the same Idempotency-Key with a different payload.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

409 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/idempotency_conflict",
  "title": "Idempotency conflict",
  "status": 409,
  "code": "idempotency_conflict",
  "detail": "This Idempotency-Key was used with a different payload.",
  "run_id": "run_8f2c1ad04b"
}

429 Too Many Requests

rate_limit_exceeded or concurrency_limit_exceeded, with Retry-After.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

429 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "60 requests per minute per key. Retry after the number of seconds in `Retry-After`.",
  "limit": 60
}

502 Bad Gateway

A Run that opened and then failed is answered as application/problem+json with its problem's status — vendor_error here, not_found as 404 — and the Run envelope alongside, so the Run id is kept. A failed Run is never charged.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

502 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/vendor_error",
  "title": "Vendor error",
  "status": 502,
  "code": "vendor_error",
  "detail": "The upstream data provider could not be reached.",
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "ad_lookup",
    "status": "failed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  }
}

503 Service Unavailable

source_unavailable: every source this Run reads failed or is switched off. The Run fails uncharged, with its envelope alongside; endpoints names the source. Retry later rather than treating it as empty.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

503 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/source_unavailable",
  "title": "Source unavailable",
  "status": 503,
  "code": "source_unavailable",
  "detail": "The tiktok/video source is unavailable right now.",
  "endpoints": [
    "tiktok/video"
  ],
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "ad_lookup",
    "status": "failed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  }
}

Request samples

curl "https://www.shortsintel.com/v1/ads/meta/library_id_example?analyze=true&wait=30" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/ads/meta/library_id_example?analyze=true&wait=30",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/ads/meta/library_id_example?analyze=true&wait=30",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

This call creates a Run. With wait it holds the response open until the Run finishes or the wait runs out, then answers with the finished result or 202 and the running Run. Poll GET /v1/runs/{id} until it settles; re-reading a Run is free.

Runs: How a call becomes a Run, waiting inline, polling and free re-reads.
Pricing and estimates: Credits, estimates and why a cached result costs the same as a fresh one.
Ads: Searching Meta's Ad Library with its filters, what each Ad carries, the winner Score, Ad analysis, what is stored, and how an ad search is priced.

Price

Parameters

Responses

200 OK

202 Accepted

400 Bad Request

401 Unauthorized

402 Payment Required

409 Conflict

429 Too Many Requests

502 Bad Gateway

503 Service Unavailable

Request samples

Related guides