At a glance
Capabilities
An unsupported call returns501 resource.not_supported.
The cross-platform matrix is on Platforms.
Connect an account
Connect withPOST /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.
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=erroranderror=platform.facebook.no_pageson yourredirect_uri. - Without a selection step, a login whose every Page belongs to another of your brands ends with
status=erroranderror=platform.facebook.no_assignable_pages. - A brand whose Facebook account is connected through a different login ends with
status=erroranderror=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 withGET /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: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.
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.
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.
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:
400 validation.days_invalid.daysis below 1 or above 365.404 account.not_found,501 resource.not_supported. The account does not exist, or{account_id}is not a Facebook account.404 resource.not_found.page_idis not an active Page of the account, or the account has no default Page.403 account.permission_missing. The account does not have theanalytics.readpermission.403 platform.facebook.insights_scope_missing. The Page was connected before 2026-10-17, its login declinedread_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.403 account.reconnection_required,401 platform.facebook.auth. The account needs reconnecting.429 platform.facebook.rate_limit,429 platform.facebook.throttled.rate_limitis Facebook’s own rate limit.throttledmeans Facebook refused the account or the Page with that limit, and SocialAPI refuses calls for it until the wait ends. Wait for theRetry-Afterheader when it is present, then retry.403,404, or503 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.
Related
- Facebook publishing: fields, media rules, and quirks for publishing
- Facebook comments: replies, private replies, and moderation on Page posts
- Facebook direct messages: Messenger DMs, the messaging window, and interactive messages
- Connect accounts: the shared connect flow
- Automations: comment-to-DM flows
- Platforms: the capability matrix