Facebook Profile API reference

Exact follower count for a public Facebook Page or personal profile; a Page also returns its name, category and verified badge. 1 credit a call.

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

Endpoint

GET /v1/facebook/profile
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/profile' \
  -H 'Authorization: Bearer sv_live_...' \
  --data-urlencode 'url=https://www.facebook.com/NASA'

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",
    "pageId": "100044561550831",
    "username": "NASA",
    "name": "NASA - National Aeronautics and Space Administration",
    "category": "Government organization",
    "avatarUrl": "https://cdn.sourcevine.io/avatar/facebook-example.jpg",
    "verified": true,
    "followerCount": 28700000,
    "followingCount": 120,
    "fetchedAt": "2026-08-28T09:41:44Z",
    "sourceTimestamp": "2026-08-27T18:04:12Z",
    "cached": false,
    "cacheAgeSeconds": 0
  }
}

Fields

Field	Type	Notes
`url`	string	The public Page or profile URL you sent.
`pageId`	string	Facebook id of the Page or profile.
`username`	string \| null	The Page's username.
`name`	string \| null	Page name. Null for a personal profile.
`category`	string \| null	Page category as Facebook shows it. Null for a personal profile.
`avatarUrl`	string \| null	Page profile picture. Null for a personal profile.
`verified`	boolean \| null	Whether the Page carries a verified badge. Null for a personal profile.
`followerCount`	integer \| null	Exact public follower count, for a Page or a personal profile.
`followingCount`	integer \| null	Accounts the Page follows, where Facebook shows it.
`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 personal profile the response carries the follower count and id. Name, category, avatar and verified badge 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