A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Meta Graph API is how an app or AI agent works with Facebook and Instagram: publishing a Page's posts, reading its insights, moderating comments, publishing to a linked Instagram account, and sending Messenger messages. Access is granted through an OAuth 2.0 access token and a set of Meta permissions, where the token type sets which Pages and accounts a call can reach, and most permissions go through App Review first. Meta versions the API by dated release and can push events to a webhook once a Page is subscribed to the app.
How an app or AI agent connects to the Meta Graph API determines what it can reach. Access runs on OAuth 2.0 access tokens, and the kind of token, a User token, a Page token, or an app token, decides which Pages and Instagram accounts a call can act on.
The Graph API answers at graph.facebook.com, with each request pinned to a dated version in its path, like v25.0. A call authenticates with an OAuth 2.0 access token, where a User token, a Page token, or an app token decides what it can reach.
Meta posts event payloads to a webhook URL registered for the app once a Page is subscribed through its subscribed_apps. Each delivery carries an X-Hub-Signature-256 header that the receiver checks against the app secret to confirm it came from Meta.
A User access token represents a person who logged in with Facebook Login and consented to a set of permissions. It is the starting point for reaching the Pages and Instagram accounts that person manages, and is usually exchanged for a long-lived token that lasts about 60 days.
A Page access token acts as a Page rather than a person, and most Page and Instagram methods need one. It is obtained from a User token through /me/accounts, and the tasks the person has on the Page, like CREATE_CONTENT, MODERATE, or MANAGE, decide what the token can do.
An app access token identifies the app itself rather than any user, formed from the app id and app secret. It is used for app-level tasks, like managing webhook subscriptions and reading public data, and must never be exposed in client code.
The Meta Graph API is split into areas an agent can act on, like a Facebook Page's posts and insights, comments and likes, an Instagram account's media, and Messenger conversations. Each area has its own methods and its own permissions, and most of those permissions go through App Review before they reach live users.
Read a Page's details, read and publish posts on its feed, publish photos, and update or delete a post.
Read a Facebook Page's metrics, like impressions, engagement, and follower counts, over a chosen period.
Read comments on a Page's posts, create and delete comments, and like a post on behalf of the Page.
Read an Instagram professional account's profile and media, publish a photo or video, and read its insights.
List a Page's Messenger conversations, read the messages in one, and send a message from the Page.
Read the authenticated person's basic public profile and the list of Pages they manage.
Subscribe a Page to the app's webhook so Meta pushes its events, and list the apps a Page is subscribed to.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Pages (posts & photos)Read a Page's details, read and publish posts on its feed, publish photos, and update or delete a post.6 | ||||||
| GET | /{page-id} | Read a Facebook Page's details, like its name, category, and metadata. | read | pages_read_engagement | Current | |
Needs a Page access token. pages_show_list also lets an app find which Pages the person manages. Acts onpage Permission (capability) pages_read_engagementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{page-id}/feed | Read the posts published on a Page's feed. | read | pages_read_engagement | Current | |
Reading another Page's public posts without managing it uses the Page Public Content Access feature, which goes through App Review. Acts onpost Permission (capability) pages_read_engagementVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{page-id}/feed | Publish a new post to a Page's feed. | write | pages_manage_posts | Current | |
Needs a Page access token from a person with the CREATE_CONTENT task. pages_manage_posts depends on pages_read_engagement and pages_show_list, and all go through App Review. Acts onpost Permission (capability) pages_manage_postsVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{page-id}/photos | Publish a photo to a Page, either to the feed or to an album. | write | pages_manage_posts | Current | |
An image can be passed as a URL or uploaded directly. Needs a Page access token with the CREATE_CONTENT task. Acts onphoto Permission (capability) pages_manage_postsVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{post-id} | Update an existing Page post, like its message text. | write | pages_manage_posts | Current | |
Needs a Page access token with the CREATE_CONTENT task. Acts onpost Permission (capability) pages_manage_postsVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /{post-id} | Delete a post from a Page. | write | pages_manage_posts | Current | |
Deletion is permanent. Needs a Page access token with the CREATE_CONTENT task. Acts onpost Permission (capability) pages_manage_postsVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Page insightsRead a Facebook Page's metrics, like impressions, engagement, and follower counts, over a chosen period.1 | ||||||
| GET | /{page-id}/insights/{metric} | Read a Page's insight metrics, like impressions, engaged users, and follower counts, over a period. | read | read_insights | Current | |
Needs read_insights plus a Page access token. Several reach and impression metrics are being removed from June 2026 in favour of media-view metrics. Acts oninsights Permission (capability) read_insightsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Comments & likesRead comments on a Page's posts, create and delete comments, and like a post on behalf of the Page.4 | ||||||
| GET | /{object-id}/comments | Read the comments on a Page's post, photo, or video. | read | pages_read_engagement | Current | |
On Page posts, photos, and videos this returns empty data with a User token, so a Page access token is required. Reading comments left by other people also needs pages_read_user_content. Acts oncomment Permission (capability) pages_read_engagementVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{object-id}/comments | Create a comment on a Page's post, photo, or video as the Page. | write | pages_manage_engagement | Current | |
Needs a Page access token with the MODERATE task. The comment carries at least a message, attachment, or source. Acts oncomment Permission (capability) pages_manage_engagementVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /{comment-id} | Delete a comment on a Page's content. | write | pages_manage_engagement | Current | |
Deleting a comment left by another person also needs pages_read_user_content. Needs a Page access token with the MODERATE task. Acts oncomment Permission (capability) pages_manage_engagementVersionAvailable since the API’s base version Webhook event feedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{object-id}/likes | Like a post or comment on behalf of the Page. | write | pages_manage_engagement | Current | |
Needs a Page access token with the MODERATE task. Acts onlike Permission (capability) pages_manage_engagementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{ig-user-id} | Read an Instagram professional account's profile, like its username, follower count, and biography. | read | instagram_basic | Current | |
The Instagram account is reached through the Facebook Page it is linked to, so the call also needs pages_read_engagement and a Page access token. Acts onig-user Permission (capability) instagram_basicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{ig-user-id}/media | List the media an Instagram professional account has published. | read | instagram_basic | Current | |
Also needs pages_read_engagement and a Page access token for the linked Page. Acts onig-media Permission (capability) instagram_basicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{ig-user-id}/media | Create a media container for a photo, video, reel, story, or carousel, the first step of publishing to Instagram. | write | instagram_content_publish | Current | |
The image or video must be hosted on a publicly reachable URL. Also needs instagram_basic, pages_read_engagement, and a Page access token. instagram_content_publish goes through App Review. Acts onig-media Permission (capability) instagram_content_publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{ig-user-id}/media_publish | Publish a previously created media container to the Instagram account. | write | instagram_content_publish | Current | |
An account is limited to 100 API-published posts in a rolling 24-hour window, counted on this endpoint, where a carousel counts as one. Acts onig-media Permission (capability) instagram_content_publishVersionAvailable since the API’s base version Webhook eventNone Rate limit100 posts per 24h SourceOfficial documentation ↗ | ||||||
| GET | /{ig-media-id}/insights | Read the insights for a single Instagram media item, like reach and saves. | read | instagram_manage_insights | Current | |
Also needs a Page access token for the linked Page. instagram_manage_insights goes through App Review. Acts oninsights Permission (capability) instagram_manage_insightsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Conversations & MessengerList a Page's Messenger conversations, read the messages in one, and send a message from the Page.3 | ||||||
| GET | /{page-id}/conversations | List the Messenger or Instagram conversations in a Page's inbox. | read | pages_messaging | Current | |
The platform parameter selects messenger or instagram. Also needs pages_manage_metadata and pages_read_engagement, plus a Page access token. Acts onconversation Permission (capability) pages_messagingVersionAvailable since the API’s base version Webhook event messagesRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{conversation-id}/messages | Read the messages within a single conversation. | read | pages_messaging | Current | |
Also needs pages_read_engagement and a Page access token. Acts onmessage Permission (capability) pages_messagingVersionAvailable since the API’s base version Webhook event messagesRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{page-id}/messages | Send a message from the Page to a person in Messenger. | write | pages_messaging | Current | |
Sending outside the 24-hour standard messaging window needs an approved message tag. pages_messaging goes through App Review and needs a Page access token. Acts onmessage Permission (capability) pages_messagingVersionAvailable since the API’s base version Webhook eventNone Rate limit200 * engaged users per 24h SourceOfficial documentation ↗ | ||||||
User profileRead the authenticated person's basic public profile and the list of Pages they manage.2 | ||||||
| GET | /me | Read the authenticated person's basic public profile fields. | read | public_profile | Current | |
public_profile is granted automatically with Facebook Login. The email field needs the separate email permission, which goes through App Review. Acts onuser Permission (capability) public_profileVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/accounts | List the Pages the authenticated person manages, with a Page access token for each. | read | pages_show_list | Current | |
This is the usual way to obtain the Page access tokens the other Page methods need. Acts onpage Permission (capability) pages_show_listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksSubscribe a Page to the app's webhook so Meta pushes its events, and list the apps a Page is subscribed to.2 | ||||||
| POST | /{page-id}/subscribed_apps | Subscribe the app to a Page's webhook, so Meta pushes the chosen events for that Page. | write | pages_manage_metadata | Current | |
The subscribed_fields parameter names which Page events to receive, like feed, messages, or mention. It cannot configure Instagram webhooks. Needs a Page access token with the relevant task. Acts onsubscribed_app Permission (capability) pages_manage_metadataVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{page-id}/subscribed_apps | List the apps subscribed to a Page's webhook and the fields each receives. | read | pages_manage_metadata | Current | |
Also needs pages_show_list and a Page access token. Acts onsubscribed_app Permission (capability) pages_manage_metadataVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Meta can notify an app or AI agent when something happens on a Page or Instagram account, like a new post, a comment, or an incoming message, instead of the app polling for changes. A Page is subscribed to the app, and Meta then posts each event to the webhook URL registered for the app.
| Event | What it signals | Triggered by |
|---|---|---|
feed | Fires when a Page's feed changes, like a new post, a status update, or a new comment or like on the Page's content. | /{page-id}/feed/{page-id}/photos/{object-id}/comments |
messages | Fires when the Page receives a message in Messenger, the core event for a messaging or support agent. | In-app only |
mention | Fires when the Page is mentioned in another person's or Page's post or comment. | In-app only |
Meta limits how fast and how much an app or AI agent can call, through a platform quota that scales with daily active users and a separate business-use-case quota that scales per Page, both reported in usage headers on every response.
Meta meters calls two ways at once. The platform limit applies to calls on a User or app token and allows roughly 200 calls per hour for each daily active user the app has, summed into one app-wide pool, reported in the X-App-Usage header as call_count, total_cputime, and total_time percentages. The business-use-case limit applies to Pages, Instagram, and Marketing calls, and scales per Page, with the Pages quota at about 4,800 calls per engaged user over 24 hours and Messenger at about 200 per engaged user; it is reported in X-Business-Use-Case-Usage, which also returns estimated_time_to_regain_access in minutes once throttled. Going over returns an error with code 4 for the app limit, 17 for a user, or 32 for a Page. Instagram publishing has its own ceiling of 100 posts per account in a rolling 24-hour window.
List results are cursor-paginated. A response carries a paging object with before and after cursors and next and previous URLs, and the limit parameter sets the page size. Some edges also support time-based paging through the since and until parameters, and offset paging through offset, though cursor paging is preferred for large or changing sets.
Direct photo and video uploads are bounded by per-media size and length limits that vary by media type, and large videos use a resumable upload session rather than a single request. Instagram media must be hosted on a publicly reachable URL at the moment of publishing. An fbtrace_id returned on an error is a short-lived support identifier, not a stable record.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | 100 (invalid parameter) | A parameter is missing, malformed, or not valid for the request. The error object carries a message, type, code, error_subcode, and an fbtrace_id for support. | Read the message and error_subcode, correct the named parameter, and resend. |
| 400 | 190 (access token expired or invalid) | The access token is missing, expired, revoked, or otherwise invalid. error_subcode often gives the precise reason, like the user changed their password or revoked consent. | Obtain a fresh token, re-running Facebook Login if the person needs to re-consent. |
| 403 | 200 (permission denied) | The token does not carry the permission the request needs, or the person lacks the required task on the Page. | Request the missing permission, get it approved in App Review, and confirm the person's Page task. |
| 403 | 4 (application rate limit) | The app exceeded its platform rate limit, which scales with the app's daily active users. | Slow the request rate and retry later. The X-App-Usage header reports how close to the limit the app is. |
| 403 | 32 (page rate limit) | A Page-level business-use-case rate limit was hit, which scales with the Page's engaged users. | Back off using estimated_time_to_regain_access from the X-Business-Use-Case-Usage header, then retry. |
| 500 | 2 (service temporarily unavailable) | A temporary problem on Meta's side, which is usually transient. | Retry the request with exponential backoff. |
Meta versions the Graph API by dated release, named like v25.0, and pins each call to the version in its path. The newest version is v25.0, released on 18 February 2026, and each version is supported for about two years before it expires.
Graph API v25.0 was released on 18 February 2026. It begins the deprecation of several reach and impression metrics across the Page, Post, Video, and Stories Insights APIs, which are replaced by media-view and media-viewer metrics from June 2026, and deprecates the metadata=1 query parameter. A separate infrastructure change moves Webhooks mTLS certificates to a Meta-owned Certificate Authority from 31 March 2026.
Graph API v24.0 was released on 8 October 2025, continuing the roughly quarterly version cadence ahead of v25.0.
Graph API v23.0 was released on 29 May 2025.
Graph API v22.0 was released on 21 January 2025.
An integration can pin a version in the request path and move up on a schedule that suits it.
Meta Graph API changelog ↗Bollard AI sits between a team's AI agents and the Meta Graph API. Grant each agent exactly the access it needs, read or write, Page by Page, and every call is checked and logged.