Facebook API
The TrueScrape Facebook API exposes 22 public endpoints covering Ad details, Ad video transcript and Find advertisers running ads. Every call is a GET against public, logged-out pages and returns the same unified schema as every other platform here. Calls cost 1–2 credits each. A cache hit is free, and a failed or empty response is never charged.
Endpoints
| Endpoint | Returns | Credits | Cacheable | Batchable |
|---|---|---|---|---|
| /v1/facebook/ad-library/ad | Ad details | 1 | yes | yes |
| /v1/facebook/ad-library/ad-transcript | Ad video transcript | 1 | yes | yes |
| /v1/facebook/ad-library/advertisers | Find advertisers running ads | 1 | yes | yes |
| /v1/facebook/ad-library/page-ads | All ads for one advertiser | 2 | yes | yes |
| /v1/facebook/ad-library/search | Search the Meta Ad Library | 2 | yes | yes |
| /v1/facebook/city-events | Get the events of a city | 1 | yes | yes |
| /v1/facebook/comment-replies | Replies to a comment | 1 | yes | yes |
| /v1/facebook/event | Event details | 1 | yes | yes |
| /v1/facebook/events/search | Search public events | 1 | yes | yes |
| /v1/facebook/group | Public group info | 1 | yes | yes |
| /v1/facebook/group-posts | Public group posts | 1 | yes | yes |
| /v1/facebook/marketplace/item | Marketplace listing details | 1 | yes | yes |
| /v1/facebook/marketplace/locations | Find a Marketplace location | 1 | yes | yes |
| /v1/facebook/marketplace/search | Search Marketplace listings | 1 | yes | yes |
| /v1/facebook/page-posts | Public Page posts | 1 | yes | yes |
| /v1/facebook/page-reels | Public Page videos and reels | 1 | yes | yes |
| /v1/facebook/post | Single post, video, or reel | 1 | yes | yes |
| /v1/facebook/post-comments | Comments on a post | 1 | yes | yes |
| /v1/facebook/post-transcript | Video transcript | 1 | yes | yes |
| /v1/facebook/profile | Public Page profile | 1 | yes | yes |
| /v1/facebook/profile-events | Events on a Page | 1 | yes | yes |
| /v1/facebook/profile-photos | Photos on a Page | 1 | yes | yes |
Reference
/v1/facebook/ad-library/ad1 creditcacheablebatchableAd details
One ad from the Meta Ad Library by its archive id. Meta does not expose the archive as an addressable node for every ad; pass page_id as well and we find it by scanning that advertiser's archive instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Ad archive id, or an Ad Library URL containing ?id= |
| page_id | string | no | The advertiser's page id. Enables the archive-scan fallback. |
| country | string | no | Reached country used by the fallback scandefaults to US |
| url | string | no | Ad archive id, or an Ad Library URL containing ?id= |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns one Ad.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 47 strings | always | |
| id | string | always | |
| advertiserId | string | null | always | |
| advertiserName | string | null | always | |
| url | string | null | always | Link to the ad's page in the platform's ad library. |
| headline | string | null | always | |
| body | string | null | always | |
| ctaText | string | null | always | Text of the call-to-action button, such as "Shop now". |
| linkUrl | string | null | always | Where the ad links to. Some ad libraries expose only the destination's domain. |
| creativeType | string | null | always | Format of the ad creative, such as `video` or `image`, as the ad library labels it. |
| imageUrls | string[] | always | |
| videoUrls | string[] | always | |
| platforms | string[] | always | Platforms the ad was shown on, in lowercase, such as `facebook` or `instagram`. |
| countries | string[] | always | Countries the ad ran in or targeted, usually as two-letter country codes. |
| languages | string[] | always | |
| startedAt | string | null | always | |
| endedAt | string | null | always | When the ad stopped running. Null while it is still running, or when the ad library reports no end date. |
| isActive | boolean | null | always | |
| impressionsLower | number | null | always | Lower bound of the impressions range the ad library reports. Libraries publish a range, not an exact figure. |
| impressionsUpper | number | null | always | Upper bound of the impressions range the ad library reports. |
| spendLower | number | null | always | Lower bound of the reported spend range, in `currency`. |
| spendUpper | number | null | always | Upper bound of the reported spend range, in `currency`. |
| currency | string | null | always | Currency of the spend range, as a code such as `USD`. |
| fetchedAt | string | always | When this record was fetched from the platform, as an ISO 8601 timestamp. A cached response keeps the time of the original fetch. |
curl "$API/v1/facebook/ad-library/ad?id=%3Cid%3E&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
id: '<id>',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/facebook/ad-library/ad?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/facebook/ad-library/ad",
params={
"id": "<id>",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or rate_limited (hourly calls to servers you named outside our known list). Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_schema_drift. Not charged |
| 503 | upstream_unavailable. We could not get this from the platform. Not charged |
| 504 | upstream_timeout. Not charged |
/v1/facebook/ad-library/ad-transcript1 creditcacheablebatchableAd video transcript
Retrieves a transcript for a single Facebook Ad Library video ad by ID or URL, read from the caption track Facebook publishes for the ad's video (source: "captions"). Transcription of ad videos without captions is coming soon; until then those answer not_configured (501) and are not charged. Credits are only deducted when a transcript is actually returned. **Required:** Pass exactly one of id or url.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | no | Ad archive id, or an Ad Library URL containing ?id= |
| url | string | no | An Ad Library URL containing ?id= |
| language | string | no | Preferred caption locale |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns one Transcript.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 47 strings | always | |
| postId | string | always | |
| url | string | null | always | |
| language | string | null | always | The transcript's language as the platform labels it, usually a language code such as `en`. |
| isAutoGenerated | boolean | null | always | Whether the platform generated the captions automatically, by speech recognition or machine translation, rather than a person writing them. |
| text | string | always | The full transcript as a single block of text. |
| cues | object[] | always | Timed segments of the transcript. |
| cues[].start | number | always | Seconds from the start of the media. |
| cues[].end | number | null | always | Seconds from the start of the media. Null when the platform gives no end time. |
| cues[].text | string | always | |
| durationSeconds | number | null | always | |
| source | captions | asr | null | always | Where the transcript came from. `captions`: the platform's own caption track, whether a person wrote it or the platform generated it (see `isAutoGenerated`). `asr`: produced by speech recognition on the audio. Null when this cannot be told. |
| fetchedAt | string | always | When this record was fetched from the platform, as an ISO 8601 timestamp. A cached response keeps the time of the original fetch. |
curl "$API/v1/facebook/ad-library/ad-transcript?cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/facebook/ad-library/ad-transcript?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/facebook/ad-library/ad-transcript",
params={
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or rate_limited (hourly calls to servers you named outside our known list). Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_schema_drift. Not charged |
| 503 | upstream_unavailable. We could not get this from the platform. Not charged |
| 504 | upstream_timeout. Not charged |
/v1/facebook/group1 creditcacheablebatchablePublic group info
Name, member count, privacy setting and description for a public Facebook group. Member count lands in followerCount (a group's equivalent of an audience size) and the privacy setting in category. Facebook rounds that count on large groups ("12K members"); raw.memberCountIsApproximate says whether the number you got was rounded.
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | yes | Group URL, group id, or group slug |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns one Creator.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 47 strings | always | |
| id | string | always | The platform's own id for the account, such as a channel id or a numeric user id, always as a string. |
| handle | string | null | always | The account handle without the leading @. Null when the platform has no handles. |
| displayName | string | null | always | |
| bio | string | null | always | |
| avatarUrl | string | null | always | |
| bannerUrl | string | null | always | |
| url | string | null | always | |
| verified | boolean | null | always | Whether the platform shows a verification badge on the account. Null where the platform has no public badge or does not expose it. |
| followerCount | number | null | always | Followers, subscribers, or the platform's nearest equivalent. Null when the account hides the count or the platform does not expose it. |
| followingCount | number | null | always | |
| postCount | number | null | always | Posts, videos, tracks, repositories, or the platform's nearest equivalent that the account has published. |
| viewCount | number | null | always | Lifetime views across the account, where the platform exposes a total. |
| likeCount | number | null | may be absent | Total likes received across all of the creator's posts. Distinct from `viewCount`. Absent when the platform does not expose it. |
| isPrivate | boolean | null | always | |
| isBusiness | boolean | null | always | Whether the platform classifies the account as a business or organisation rather than a person or creator. Null where the platform draws no such line or does not expose it. On Facebook every Page counts, including Pages for public figures. |
| category | string | null | always | A label the platform attaches to the account, such as a business category, a genre or an account type. What it holds varies by platform. |
| location | string | null | always | Location as the platform shows it: a city, a country, a region code or an address, depending on the platform. |
| externalLinks | string[] | always | Links the account lists on its profile, such as a website or other social accounts. |
| createdAt | string | null | always | When the account was created. Usually an ISO 8601 timestamp; some platforms expose only the date as shown on the profile. |
| fetchedAt | string | always | When this record was fetched from the platform, as an ISO 8601 timestamp. A cached response keeps the time of the original fetch. |
curl "$API/v1/facebook/group?url=8XkPqR2nLvE&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
url: '8XkPqR2nLvE',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/facebook/group?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/facebook/group",
params={
"url": "8XkPqR2nLvE",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or rate_limited (hourly calls to servers you named outside our known list). Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_schema_drift. Not charged |
| 503 | upstream_unavailable. We could not get this from the platform. Not charged |
| 504 | upstream_timeout. Not charged |
/v1/facebook/group-posts1 creditcacheablebatchablePublic group posts
Recent posts from a public Facebook group, with reaction, comment and share counts where Facebook renders them. Only the newest few stories render to a logged-out visitor, the same limit /v1/facebook/page-posts has. Private groups return an empty result; their posts are not public and we do not log in.
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | yes | Group URL, group id, or group slug |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns a list of Post in data.items.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 47 strings | always | |
| id | string | always | |
| type | video | short | image | carousel | text | live | story | reel | audio | album | episode | unknown | always | What kind of post this is. `short` and `reel` are short-form video formats, `live` is a live stream or a recording of one, `carousel` holds several images or videos, `audio` is a music track, `album` is an album, `episode` is a podcast episode, and `unknown` covers anything else. |
| url | string | null | always | |
| title | string | null | always | |
| text | string | null | always | The post's text: a caption, a description or the message body. |
| authorId | string | null | always | |
| authorHandle | string | null | always | |
| authorName | string | null | always | |
| thumbnailUrl | string | null | always | |
| mediaUrls | string[] | always | |
| durationSeconds | number | null | always | |
| viewCount | number | null | always | Views. Null means the platform did not expose a count, which is not the same as zero. |
| likeCount | number | null | always | Likes, or the platform's nearest equivalent. Null means not exposed, not zero. |
| commentCount | number | null | always | Comments. Null means not exposed, not zero. |
| shareCount | number | null | always | Shares, reposts, or the platform's nearest equivalent. Null means not exposed, not zero. |
| hashtags | string[] | always | Hashtags or the platform's own topic tags, without the leading #. |
| mentions | string[] | always | Handles mentioned in the post text, without the leading @. |
| taggedUsers | string[] | may be absent | Usernames tagged in the media itself, as distinct from `mentions`, which come from the caption text. Absent when the platform does not report tags; an empty array means it reports none. |
| isSponsored | boolean | null | always | Whether the platform labels the post as an ad, promoted content or a paid partnership. |
| publishedAt | string | null | always | When the post was published. Usually an ISO 8601 timestamp; some platforms expose only a date or relative text such as "3 days ago". |
| fetchedAt | string | always | When this record was fetched from the platform, as an ISO 8601 timestamp. A cached response keeps the time of the original fetch. |
curl "$API/v1/facebook/group-posts?url=8XkPqR2nLvE&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
url: '8XkPqR2nLvE',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/facebook/group-posts?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/facebook/group-posts",
params={
"url": "8XkPqR2nLvE",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or rate_limited (hourly calls to servers you named outside our known list). Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_schema_drift. Not charged |
| 503 | upstream_unavailable. We could not get this from the platform. Not charged |
| 504 | upstream_timeout. Not charged |
/v1/facebook/marketplace/item1 creditcacheablebatchableMarketplace listing details
One public Facebook Marketplace listing: title, full description, price, location, delivery options and every photo. Facebook does not render the seller to a logged-out visitor, so seller identity is not returned.
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | yes | Marketplace item URL or numeric listing id |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns an object with platform, id, title, url, description, priceText, priceAmount, originalPriceText, isSold, isPending, isLive, locationText, city, state, categoryId, deliveryTypes, thumbnailUrl, imageUrls, listedAt, fetchedAt.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | "facebook" | always | |
| id | string | always | |
| title | string | null | always | |
| url | string | always | |
| description | string | null | always | |
| priceText | string | null | always | As Facebook formatted it, e.g. "$150", carrying the currency symbol. |
| priceAmount | number | null | always | Numeric amount in the listing's own currency. |
| originalPriceText | string | null | always | The pre-discount price, when the seller marked one down. |
| isSold | boolean | null | always | |
| isPending | boolean | null | always | |
| isLive | boolean | null | always | |
| locationText | string | null | always | |
| city | string | null | always | |
| state | string | null | always | |
| categoryId | string | null | always | |
| deliveryTypes | string[] | always | |
| thumbnailUrl | string | null | always | |
| imageUrls | string[] | always | Up to ten, the first of which is `thumbnailUrl`. |
| listedAt | string | null | always | |
| fetchedAt | string | always |
curl "$API/v1/facebook/marketplace/item?url=8XkPqR2nLvE&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
url: '8XkPqR2nLvE',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/facebook/marketplace/item?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/facebook/marketplace/item",
params={
"url": "8XkPqR2nLvE",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or rate_limited (hourly calls to servers you named outside our known list). Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_schema_drift. Not charged |
| 503 | upstream_unavailable. We could not get this from the platform. Not charged |
| 504 | upstream_timeout. Not charged |
/v1/facebook/marketplace/search1 creditcacheablebatchableSearch Marketplace listings
Public Facebook Marketplace listings matching a search term, with price, condition flags, location and photos. location takes a city slug or a location id from /v1/facebook/marketplace/locations; without one, Facebook picks the city it places the request in, which you do not control. Pass location for results you can repeat.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | yes | What to search for, e.g. "mountain bike" |
| location | string | no | City slug ("nyc", "london") or a location id from /v1/facebook/marketplace/locations |
| min_price | number | no | Lowest price, in the location's currency |
| max_price | number | no | Highest price, in the location's currency |
| days_since_listed | number | no | Only listings posted in the last N days |
| radius_km | number | no | Search radius around the location, in kilometres |
| sort_by | best_match | creation_time_descend | price_ascend | price_descend | distance_ascend | no | Facebook's own sort keys |
| delivery_method | local_pick_up | shipping | no | Restrict to collection-only or shipped listings |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns a list of object in data.items.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | "facebook" | always | |
| id | string | always | |
| title | string | null | always | |
| url | string | always | |
| description | string | null | always | |
| priceText | string | null | always | As Facebook formatted it, e.g. "$150", carrying the currency symbol. |
| priceAmount | number | null | always | Numeric amount in the listing's own currency. |
| originalPriceText | string | null | always | The pre-discount price, when the seller marked one down. |
| isSold | boolean | null | always | |
| isPending | boolean | null | always | |
| isLive | boolean | null | always | |
| locationText | string | null | always | |
| city | string | null | always | |
| state | string | null | always | |
| categoryId | string | null | always | |
| deliveryTypes | string[] | always | |
| thumbnailUrl | string | null | always | |
| imageUrls | string[] | always | Up to ten, the first of which is `thumbnailUrl`. |
| listedAt | string | null | always | |
| fetchedAt | string | always |
curl "$API/v1/facebook/marketplace/search?query=ai%20agents&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
query: 'ai agents',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/facebook/marketplace/search?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/facebook/marketplace/search",
params={
"query": "ai agents",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or rate_limited (hourly calls to servers you named outside our known list). Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_schema_drift. Not charged |
| 503 | upstream_unavailable. We could not get this from the platform. Not charged |
| 504 | upstream_timeout. Not charged |
Questions
- How much does the Facebook API cost?
- Calls cost 1–2 credits each. Every endpoint is cacheable, and a cache hit costs nothing. A failed request and an empty result are both free, on every endpoint.
- Does the Facebook API need a login or cookies?
- No. Every endpoint reads public, logged-out pages only — no account, no cookies, no session. An API key identifies your own TrueScrape account and nothing else.
- Can I fetch many Facebook targets in one request?
- Yes. 22 of 22 are batchable: one POST to /v1/jobs/batch takes many targets and returns a job id to poll.
- Can I watch Facebook endpoints for changes?
- Yes, 15 of 22. A subscription polls on your schedule and fires your webhook only when the content changed; the rest carry x-subscribable: false in the spec.