Skip to content

Post on Facebook with API: Pages, Media, Scheduling, and Analytics

You can post on Facebook with API calls that target Facebook Pages, not personal profiles. This guide walks through the exact request contract for connecting a Page, publishing text, images, carousels, video, and link previews, scheduling a post, cross-posting, and pulling analytics. The native Facebook Graph API remains an alternative for teams that want to manage Meta developer apps, permissions such as pages_manage_posts, Page tokens, and App Review directly. The unified contract described here replaces that per-Page token flow with a saved integration identified by accountId, while keeping the underlying Facebook Pages scope unchanged.

Prerequisites and Pages-only scope: Facebook Pages, not personal profiles

Posting to a personal profile through the Facebook Graph API is not the target here. The scope is Facebook Pages, and any implementation must start from a Page the user administers. That constraint matters when you choose between a native integration and a unified posting contract. With the native Facebook Graph API, you register a Meta developer app, request permissions including pages_show_list, pages_read_engagement, and pages_manage_posts, complete App Review where required, and manage the difference between user tokens, Page tokens, and short-lived versus long-lived tokens. With the unified contract in this guide, you connect the Page once, store the returned integration id as accountId, and send that value in every POST /v1/posts request. The decision criteria are operational: choose the native path if you need direct control over Meta app configuration and token lifecycle, and choose the unified contract if you want one platforms array, one mediaItems shape, and one scheduling shape across Facebook, Instagram, and LinkedIn. Before you write any post code, confirm three prerequisites: you have an API key, you administer the Facebook Page, and that Page appears in the connected integrations list with a usable accountId. If the Page is not connected, the post request has no valid target, regardless of how well-formed the content payload is.

Get your API key, connect your Facebook Page, and retrieve accountId

Every request in this contract uses the x-access-key header. Treat the key like a password, store it outside source control, and send it on connect, integration-list, post, and analytics calls. The first step is to request the Facebook connect URL with a GET to /v1/connect/facebook. Open the returned URL in a browser, authorize the app, and select the Facebook Pages you want to make available for posting. Each selected Page becomes a separate integration. Then call GET /v1/connect/integrations with the same x-access-key header and find the id for the Page you intend to target. That id is the accountId you will reuse in the platforms array. A common failure at this stage is copying a Facebook Page ID from the Facebook interface instead of the integration id returned by the integrations endpoint. Those values are not interchangeable in this contract. Another failure is selecting a Page in the browser flow but never verifying it in the integrations response. Always list integrations after connecting and confirm the exact accountId before your first POST /v1/posts call. The worked examples for connecting and listing integrations are shown in the code examples titled Connect Facebook and get an authorization URL and List connected integrations to obtain accountId.

Post a text update with publishNow

A text post is the simplest case and the best first test of your key, integration, and accountId. Send a POST to /v1/posts with content for the caption, a platforms array containing one object with platform set to facebook and accountId set to your connected Page integration id, and publishNow set to true for immediate publication. In the source-described routing, this text payload is sent to the Page feed with the Page token resolved from the saved integration, and the response includes the published post URL. Keep the first test short and verifiable so you can confirm the post appears on the correct Page before adding media or scheduling. The source notes a hard caption ceiling of 63,206 characters for Facebook, but practical Page posts should stay far below that. If a text post fails, check the failure matrix below in order: missing or invalid x-access-key, an accountId that does not match a connected integration, and a publishNow versus scheduledFor conflict. The worked example is shown in the code examples titled Post a text update with publishNow.

Post an image carousel or video with mediaItems

For images, add mediaItems to the same POST /v1/posts payload. Each item uses type set to image and url set to a publicly reachable image URL. A single image is routed to the Page photos endpoint in the source description. Multiple images form a carousel: the source describes uploading each image as unpublished, collecting the returned media IDs, and then posting to the feed with attached_media. Facebook supports up to 10 photos per Page post as stated in the source, so keep carousel payloads at or below that limit and verify every URL loads before you send the request. If one URL returns an error or requires authentication, the whole carousel can fail even though the text and accountId are correct. For video, keep the same mediaItems shape and change type to video. The source describes routing video posts to the Page videos endpoint, with encoding and thumbnail generation handled server-side by Facebook. Use a direct, reachable video URL and confirm the file format and size are acceptable to the destination before publishing. The worked examples are shown in the code examples titled Post an image carousel with mediaItems and Post a video with mediaItems type video.

Schedule a Facebook post with scheduledFor and timezone

To schedule a Facebook post, replace publishNow with scheduledFor and timezone in the POST /v1/posts payload. The example uses scheduledFor set to 2026-06-15T09:00:00 and timezone set to America/New_York, which queues the post for that local time instead of publishing immediately. Always send both fields together: scheduledFor without a timezone is ambiguous, and a timezone without a scheduledFor has nothing to schedule. Avoid sending publishNow true alongside scheduledFor, because the contract presents them as alternative timing modes and combining them creates an immediate-versus-scheduled conflict. After scheduling, verify the queued item in your posts view by status, platform, and date before assuming it will publish. The worked example is shown in the code examples titled Schedule a Facebook post with scheduledFor and timezone.

Cross-post to other platforms and pull Facebook analytics

Cross-posting uses the same POST /v1/posts contract with multiple entries in the platforms array. Add one object per destination, each with its own platform and accountId, so Facebook, Instagram, and LinkedIn can each resolve their saved integration. The source describes different per-platform upload flows behind the single request, including Facebook photos, Instagram container and publish steps, and LinkedIn image handling, but your request shape stays the same. That uniformity is the main benefit of the unified contract, and it also means a wrong accountId for any one platform can fail that destination while the others succeed, so check each platform result in the response rather than treating the request as all-or-nothing. For analytics, use the Facebook Analytics API through a GET to /v1/analytics with source set to platform, platform set to facebook, accountId set to your Page integration id, and limit set to the number of posts you want returned. The source states that each analytics call costs 1 credit regardless of how many posts come back, and that the response includes likes, comments, and shares per Page post. The worked examples are shown in the code examples titled Cross-post to Facebook, Instagram, and LinkedIn and Pull Facebook Page analytics.

Field map, failure matrix, and pre-flight checklist

Use the field map and failure matrix below as a pre-flight checklist before every publish. Confirm your x-access-key is present, your accountId came from the integrations list, your mediaItems URLs are reachable, your platformSpecificData link target has Open Graph tags if you want a preview, and your timing fields use either publishNow or scheduledFor with timezone, not both. If a request fails, work through the matrix from authentication to target to payload to timing to analytics cost. That order isolates the most common causes first: a missing key, an unconnected Page, an unsupported media type, missing Open Graph tags, a scheduling conflict, or an unexpected credit cost on analytics. Once those checks pass, the examples in this guide cover the full reader task from a first text post through carousels, video, link previews, scheduling, cross-posting, and analytics.

POST /v1/posts and analytics field map
FieldLocationType as shownRequiredness as shownNotes
x-access-keyHeaderstringRequired in every exampleAuthentication header for connect, integrations, posts, and analytics calls.
contentPOST /v1/posts bodystringShown in every post exampleCaption or text for the post.
platformsPOST /v1/posts bodyarrayShown in every post exampleOne object per destination platform.
platforms[].platformplatforms array itemstring enum: facebook | instagram | linkedinShown in every post exampleDestination platform identifier.
platforms[].accountIdplatforms array itemstringShown in every post exampleIntegration id returned by GET /v1/connect/integrations for the connected Page or account.
platforms[].platformSpecificData.linkplatforms array itemstring (URL)Optional; shown in link-preview exampleTarget URL for Facebook Open Graph link preview.
platforms[].platformSpecificData.publishedplatforms array itembooleanOptional; described for draft stateSet to false to create an unpublished/draft Page post.
mediaItemsPOST /v1/posts bodyarrayOptional; shown in media examplesImage or video payloads for the post.
mediaItems[].typemediaItems array itemstring enum: image | videoRequired when mediaItems is presentMedia kind; image for photos/carousels, video for video posts.
mediaItems[].urlmediaItems array itemstring (URL)Required when mediaItems is presentPublicly reachable media URL.
publishNowPOST /v1/posts bodybooleanShown for immediate postsSet to true to publish immediately; alternative to scheduledFor/timezone.
scheduledForPOST /v1/posts bodystring (datetime)Shown for scheduled postsQueued publish time; use with timezone instead of publishNow.
timezonePOST /v1/posts bodystringShown with scheduledForTimezone for scheduledFor, e.g. America/New_York.
sourceGET /v1/analytics querystring: platformShown in analytics exampleAnalytics source selector.
platformGET /v1/analytics querystring: facebookShown in analytics exampleAnalytics platform selector.
accountIdGET /v1/analytics querystringShown in analytics exampleConnected Page integration id.
limitGET /v1/analytics queryinteger as shown: 20Shown in analytics exampleMaximum number of posts to return.

Requiredness reflects the worked examples in the captured source; validate against the immutable contract sheet at implementation.

Failure matrix
FailureLikely causeCheckFix
Missing x-access-keyHeader omitted or key invalidConfirm the header is sent on connect, integrations, posts, and analytics callsAdd x-access-key with a valid key and retry
Unconnected Page or wrong accountIdaccountId copied from Facebook UI or Page not selected during connectCall GET /v1/connect/integrations and match the id to the intended PageReconnect the Page and use the returned integration id as accountId
Unsupported media typemediaItems type outside image | videoInspect each mediaItems item typeUse type image or type video only
Unreachable media URLCDN URL returns an error or requires authenticationOpen each mediaItems url directlyReplace with a publicly reachable URL and retry
Missing Open Graph tagsLink target lacks og:title, og:image, or og:descriptionInspect the target page head tagsAdd Open Graph tags or accept a plain text post with the URL
Scheduled versus immediate conflictpublishNow and scheduledFor sent togetherInspect timing fields in the request bodyUse publishNow for immediate posts or scheduledFor with timezone for queued posts
Analytics credit costEach analytics call costs 1 credit as capturedCheck credit balance before repeated analytics callsBatch analytics requests with an appropriate limit instead of polling per post

Failure descriptions are derived from the captured contract and examples; exact error responses are not supplied in the source.

Connect Facebook and get an authorization URL
curl {{API_BASE_URL}}/v1/connect/facebook \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations to obtain accountId
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Post a text update with publishNow
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "facebook",
        "accountId": "your-page-id"
      }
    ],
    "publishNow": true
  }'
Post an image carousel with mediaItems
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes from this week'\''s launch →",
    "platforms": [
      { "platform": "facebook", "accountId": "your-page-id" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://your-cdn.com/photo-1.jpg" },
      { "type": "image", "url": "https://your-cdn.com/photo-2.jpg" },
      { "type": "image", "url": "https://your-cdn.com/photo-3.jpg" }
    ],
    "publishNow": true
  }'
Post a video with mediaItems type video
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "facebook", "accountId": "your-page-id" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://your-cdn.com/demo.mp4" }
    ],
    "publishNow": true
  }'
Share a link with a preview via platformSpecificData
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "facebook",
        "accountId": "your-page-id",
        "platformSpecificData": {
          "link": "https://example.com/article"
        }
      }
    ],
    "publishNow": true
  }'
Schedule a Facebook post with scheduledFor and timezone
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "facebook", "accountId": "your-page-id" }
    ],
    "scheduledFor": "2026-06-15T09:00:00",
    "timezone": "America/New_York"
  }'
Cross-post to Facebook, Instagram, and LinkedIn
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "facebook", "accountId": "your-page-id" },
      { "platform": "instagram", "accountId": "your-ig-id" },
      { "platform": "linkedin", "accountId": "your-li-id" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://your-cdn.com/launch.jpg" }
    ],
    "publishNow": true
  }'
Pull Facebook Page analytics
curl "{{API_BASE_URL}}/v1/analytics?source=platform&platform=facebook&accountId=your-page-id&limit=20" \
  -H "x-access-key: YOUR_API_KEY"