Facebook Post Stats API reference

Reactions, comments, shares, views and plays for a public Facebook post, video or reel, by a Page or a person. Takes a public URL, 1 credit a call.

This named API keeps Facebook fields in Facebook's own vocabulary. For a higher-level product page, see Facebook Post Stats API.

Endpoint

GET /v1/facebook/stats
Authorization: Bearer sv_live_...

`POST` is also accepted with the same parameters in the request body. Send the key in the `Authorization` header, never in the query string.

Parameters

Name	Type	Required	Notes
`url`	string	yes	Public Facebook URL matching this API's input.

Sample Request

This is a copyable request shape. Replace the sample values with the public Facebook target or parameters your workflow uses.

curl -G 'https://api.sourcevine.io/v1/facebook/stats' \
  -H 'Authorization: Bearer sv_live_...' \
  --data-urlencode 'url=https://www.facebook.com/NASA/posts/1644708777024492'

Sample Response

The response below is illustrative: this endpoint has no verified recording. Live values depend on the public resource and its availability.

{
  "success": true,
  "available": true,
  "data": {
    "url": "https://www.facebook.com/NASA/posts/1644708777024492",
    "postId": "1644708777024492",
    "text": "A new image from the telescope: a stellar nursery 7,000 light-years away.",
    "pageId": "100044561550831",
    "pageUsername": "NASA",
    "pageLink": "https://www.facebook.com/NASA",
    "reactions": 18400,
    "comments": 612,
    "shares": 2150,
    "views": null,
    "plays": null,
    "durationSeconds": null,
    "mediaType": "image",
    "publishedAt": "2026-08-27T18:04:12Z",
    "fetchedAt": "2026-08-28T09:41:44Z",
    "sourceTimestamp": "2026-08-27T18:04:12Z",
    "cached": false,
    "cacheAgeSeconds": 0
  }
}

Fields

Field	Type	Notes
`url`	string	The public post, video or reel URL you sent.
`postId`	string	Facebook post or video id.
`text`	string \| null	Public post text after contact-detail scrubbing. Null on a personal profile's post.
`pageId`	string \| null	Id of the Page that published the post.
`pageUsername`	string \| null	The Page's username. Null on a personal profile's post.
`pageLink`	string \| null	Link to the publishing Page. Null on a personal profile's post.
`reactions`	integer \| null	All reactions, of which a like is one kind. Where Facebook only shows a rounded figure such as 14K, this is that figure; null when no figure says more.
`comments`	integer \| null	Public comment count.
`shares`	integer \| null	Public share count. Null on a video's page, where Facebook does not show it.
`views`	integer \| null	Video views where Facebook publishes them. Null on a photo or text post.
`plays`	integer \| null	Video and reel plays where Facebook publishes them, separate from views.
`durationSeconds`	number \| null	Length of a video or reel.
`mediaType`	string \| null	video or image, when Facebook says which.
`publishedAt`	ISO datetime \| null	When the post was published.
`fetchedAt`	ISO datetime	When Sourcevine read the public page.
`sourceTimestamp`	ISO datetime \| null	The platform timestamp when it is available.
`cached`	boolean	True when this answer repeats an identical request made moments earlier.
`cacheAgeSeconds`	integer	Seconds since the reading was taken.

Availability States

Status	Charged	Client behavior
`available`	yes for live reads	Use data.
`unsupported`	no	Fix the URL or call the matching API. Groups, stories and events are always unsupported.
`not_found`	yes	Facebook did not show the content on two checks: missing, deleted, private or blocked. Store the state and stop polling.
`upstream_unavailable (503)`	no	Retry later with backoff.

Unavailable resources return `success: true`, `available: false`, `availability`, and `data: null`. API or authentication failures return `success: false` with an `error` object.

Billing

A call costs 1 credit. Facebook shows the same "This content isn’t available" page for content that is missing, deleted, private or blocked in a region. When a second check confirms that page, the call reports not found and is charged like any lookup. It is never reported as private, because the page does not say which case it is. If we cannot confirm it, the call returns 503 and is not charged. An unsupported URL is not charged either. The `X-Credits-Charged` response header is the source of truth for what happened on that request.

Successful responses include `fetchedAt`, the time we read the platform.

What This API Does Not Return

No contact or bio fields: Bios, email addresses, phone numbers, postal addresses and messenger handles are outside the response contract.
Personal profiles are counts only: For a post by a personal profile the response carries the counts only. The post text and the author's name are returned for Pages only.
No groups, stories or events: Groups, stories and events are not supported: those URLs are refused with a 400 before any fetch, and not charged.

Last updated 1 September 2026