List Facebook company ads
List ads a company or Page is running in the Facebook Ad Library.
Headers
Get your API keyAPI key (`sfk_...`)
Facebook page id when you have it instead of a company name.
min 1 chars · max 4096 chars
Company or page name to search when you do not have a page id.
min 1 chars · max 4096 chars
Optional country code filter. Use ALL to search all countries.
min 2 chars · max 3 chars
Optional ad status filter.
one of: all, active, inactive
Optional creative media filter.
one of: all, image, video, meme, image-and-meme, none
Optional language code filter.
min 2 chars · max 8 chars
Optional sort order for returned ads.
one of: impressions, most-recent
Optional start date filter in YYYY-MM-DD format.
pattern: ^\d{4}-\d{2}-\d{2}$
Optional end date filter in YYYY-MM-DD format.
pattern: ^\d{4}-\d{2}-\d{2}$
Opaque pagination cursor from a previous response.
min 1 chars
Endpoint-specific response payload.
Whether the company or page resolved for this request.
one of: found, not_found
Ads returned for the requested company or page. This array may be empty when the lookup resolves but no ads match the filters.
Stable identifier for the ad.
min 1 chars
Platform ad id when available.
Public Facebook Ad Library URL for this ad when available.
Advertiser page summary for this ad.
Facebook page id for the advertiser when available.
Display name for the advertiser page when available.
Public Facebook URL for the advertiser page when available.
Whether the advertiser page is marked deleted.
Profile picture URL for the advertiser page when available.
Campaign collation metadata for this ad.
Campaign collation id when available.
Number of ads in the campaign collation when available.
≥ 0
Whether the ad is currently active.
Publisher platforms where the ad ran or is running.
min 1 chars
ISO-8601 timestamp for when the ad started, when available.
ISO-8601 timestamp for when the ad ended, when available.
Ad categories reported by the platform.
min 1 chars
Countries targeted or reached by the ad when available.
min 1 chars
Impressions metadata when available.
Human-readable impressions label when available.
Impressions index when available.
Spend metadata when available.
Spend amount text when available.
Currency code for spend when available.
Creative content for this ad.
Primary ad body text when available.
Ad title when available.
Ad caption when available.
Primary link URL when available.
Link description when available.
Call-to-action label when available.
Display format for the creative when available.
Image assets attached to the creative.
Source-platform CDN URL for the image when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. This endpoint does not offer `hostMedia` durable archival.
Image width in pixels when available.
≥ 0
Image height in pixels when available.
≥ 0
Video assets attached to the creative.
Source-platform CDN URL for high-definition video when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. This endpoint does not offer `hostMedia` durable archival.
Source-platform CDN URL for standard-definition video when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. This endpoint does not offer `hostMedia` durable archival.
Source-platform CDN URL for the video preview image when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. This endpoint does not offer `hostMedia` durable archival.
Carousel cards attached to the creative.
Card title when available.
Card body text when available.
Card caption when available.
Card link URL when available.
Source-platform CDN URL for the card image when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. This endpoint does not offer `hostMedia` durable archival. Landing-page and card link URLs are never archived.
Source-platform CDN URL for the card video when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. This endpoint does not offer `hostMedia` durable archival.
Pagination information for the current response.
Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null.
Whether another page of ads can be requested.
Metadata describing the request and billing outcome.
Unique request identifier for tracing this API call.
min 1 chars
Credits charged for this request.
≥ 0
Public API version that served the response.
one of: v1
True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.
Code example
curl "https://api.socialfetch.dev/v1/facebook/ad-library/companies/ads?pageId=367152833370567" \
-H "x-api-key: YOUR_API_KEY"Responses
Ads for the requested company or page.