Skip to main content
The Facebook API in SocialAPI connects Facebook Pages. It publishes text, link, photo, video, album, Reel, and Story posts, reads and moderates comments, sends private replies and Messenger direct messages (DMs), and reads mentions. SocialAPI’s own Meta app connects the Pages, so you register nothing: see Platform apps. A Facebook profile is not supported: only Pages.

At a glance

Capabilities

An unsupported call returns 501 resource.not_supported. The cross-platform matrix is on Platforms.

Connect an account

Connect with POST /v1/accounts/connect and "platform": "facebook". The shared flow, request fields, and result are in Connect accounts, and the redirect parameters are in Redirect parameters.
Response (HTTP 202):
After the person authorizes, the redirect carries status=selection_required and a connection_id: choose the Pages that join the brand as described in Choose Facebook Pages. When facebook_page_selection is false on your SocialAPI account (GET /v1/users/me), or the connection started from an invite link, the redirect carries status=success and the brand’s Facebook account instead. That account holds every Page the login granted that none of your other brands already holds. A Page that another of your brands holds stays with that brand.
  • A login that grants no Page ends with status=error and error=platform.facebook.no_pages on your redirect_uri.
  • Without a selection step, a login whose every Page belongs to another of your brands ends with status=error and error=platform.facebook.no_assignable_pages.
  • A brand whose Facebook account is connected through a different login ends with status=error and error=account.different_login. Disconnect the brand’s Facebook account first.
  • Reconnecting the same login refreshes the access for every brand that uses it, not only the brand you reconnected from.

Pages of an account

List the Pages of a connected account with GET /v1/accounts/{account_id}/pages. Each Page has at least an id (sapi_page_ prefix), platform_page_id, name, is_default, and is_active. A Page also carries profile_picture_url, category, followers_count, username, link, verification_status, cover_photo_url, about, and enriched_at, each omitted when it has no value. Publish to a Page with page_id on the post target: see Delivery. PATCH /v1/accounts/{account_id}/pages/{page_id} sets is_default or is_active.

One login, many brands

A Facebook login is a shared credential. One login can serve many brands, and each Page belongs to exactly one brand. List every Page the login can manage on Facebook now, with the brand that holds each:
Response (HTTP 200):
login_id is on each connected account. Move a Page to a brand with POST /v1/platforms/facebook/logins/{login_id}/pages/{page_id}/assign. A Page that another of your brands holds moves to the target brand. The call needs the accounts:manage scope. Listing a login’s Pages needs accounts:read.
Response (HTTP 201):
A body without brand_id returns 400 validation.field_required, a body that is not valid JSON returns 400 validation.body_invalid, and a Page the login cannot access returns 400 validation.page_not_granted. When facebook_page_selection is true on your SocialAPI account and the brand already holds as many Facebook Pages as your plan allows, the call returns 403 platform.facebook.page_cap: see Facebook Pages per brand. An unknown login returns 404 resource.not_found, and a brand that does not exist or that your key cannot reach returns 404 brand.not_found. A brand whose Facebook account uses a different login returns 409 account.different_login.

Comments

SocialAPI lists, replies to, hides, deletes, and likes the comments on a Page’s posts, and sends private replies to commenters, acting as the Page that published the post. Every rule, limit, and error for Facebook comments is on Facebook comments.

Direct messages

SocialAPI reads the Page’s Messenger DMs and sends DMs within 24 hours of the person’s last message, with attachments, buttons, reactions, typing indicators, and seen receipts. Every rule, limit, and error for Facebook DMs is on Facebook direct messages.

Mentions

GET /v1/accounts/{account_id}/mentions returns the posts that tag the Page. A mention inside a comment is not in that list: it arrives as a mention.received event. Reply to a mention with POST /v1/accounts/{account_id}/mentions/reply, which posts a public comment. Details are in Mentions.

Page insights

GET /v1/platforms/facebook/accounts/{account_id}/summary returns the Page’s followers, views, reach, post engagements, and net follower change over the trailing 30 days.
Response (HTTP 200):
interactions counts post engagements, and net_follows is new follows minus unfollows over the period. GET /v1/platforms/facebook/accounts/{account_id}/insights/daily returns one point per day, oldest first. days sets how many trailing days, from 1 to 365 (default 365). A day with no data is left out.
Response (HTTP 200):
followers is the count at the end of the day. views, reach, and interactions are that day’s totals. Both routes take an optional page_id, the id from GET /v1/accounts/{account_id}/pages. Without it they report on the account’s default Page. Both are free, need the accounts:read scope on a scoped API key, and have no MCP tool. Both need the read_insights scope, requested since 2026-10-17 with the analytics.read permission. Post metrics in Analytics do not need it. When a Page insights call fails, check these in order:
  1. 400 validation.days_invalid. days is below 1 or above 365.
  2. 404 account.not_found, 501 resource.not_supported. The account does not exist, or {account_id} is not a Facebook account.
  3. 404 resource.not_found. page_id is not an active Page of the account, or the account has no default Page.
  4. 403 account.permission_missing. The account does not have the analytics.read permission.
  5. 403 platform.facebook.insights_scope_missing. The Page was connected before 2026-10-17, its login declined read_insights, or the person who connected it does not hold the Analyze task on the Page. A reconnect fixes the first two; for the third, grant the Analyze task on Facebook, then reconnect.
  6. 403 account.reconnection_required, 401 platform.facebook.auth. The account needs reconnecting.
  7. 429 platform.facebook.rate_limit, 429 platform.facebook.throttled. rate_limit is Facebook’s own rate limit. throttled means Facebook refused the account or the Page with that limit, and SocialAPI refuses calls for it until the wait ends. Wait for the Retry-After header when it is present, then retry.
  8. 403, 404, or 503 platform.facebook.<code>, 503 platform.facebook.api_error. Facebook returned an error that has no step above, where <code> is Meta’s error code: see Platform errors.

Reviews

SocialAPI does not read Facebook reviews: Meta deprecated Page recommendations in Graph API v22.0. GET /v1/inbox/reviews/{account_id} for a Facebook account returns 422 account.platform_unsupported, and no other call replaces it.

Webhook events

Facebook Pages emit these events to your webhook endpoints. Payloads are in Webhook events. Every post.* event in Webhook events is emitted for this platform.

Limits

A Page access token does not expire on its own. Reconnect only when a call returns 401 platform.facebook.auth, for example after the person revoked access.

Scopes

SocialAPI’s Meta app requests these scopes at connect. You apply for no app review. Each scope belongs to the account permissions in the last column, and the consent screen asks for the scopes of the permissions you selected. The scopes marked Every account are always requested. Facebook asks for messages as 1 scope, covering both reading and writing, so the consent screen shows the broader scope. The account stays limited to the permissions you selected: an account connected with messages.read alone cannot send messages.
Last modified on November 15, 2026