Graph API Version

Post /post-id

An individual entry in a profile's feed. The profile could be a User, Page, app, or group.

Reading

Graph API Explorer
GET /v3.3/post-id HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/post-id',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/post-id",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/post-id",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/post-id"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

For Posts on a User:

  • That User's access token with the user_posts permission, or
  • That User's access token, if that User used the app to create the Post, or
  • The app's access token, if that User has previously granted the app the user_posts permission, or
  • The access token for a friend of that User, with the user_friends permission, if that User has already granted the app both the user_posts and the user_friends permission.

For Posts on a Page:

  • Reading posts on a public Page requires Page Public Content Access, and responses do not include user information.
  • A Page access token can read all Posts posted to or posted by that Page, and responses will include User information.
  • The source field will not be returned for Page-owned videos unless the User making the request is an admin of the owning Page.

For Posts on a Group:

For Posts that tag Users:

  • As of April 4th, 2018, apps can no longer read Posts owned by non-app User who have been tagged by an app User. Please refer to the Breaking Changes changelog for more details.

For Posts on an Event:

  • Any valid access token of an Admin of the Event for Event-owned Posts is required after April 30, 2018.

Fields

NameTypeDescription
idstring

The ID of the post.

actionsobject

Action links on the post, Comment, Like, Share.

admin_creatorobject

The admin creator of a Page post. If the Page has only one admin, no data will be returned. Requires a Page Access Token and the business_management permission.

idint

ID of the person, app or business.

namestring

Name of the person, app or business.

allowed_advertising_objectsstring

Objectives under which this post can be advertised.

applicationobject

Information about the app this post was published by.

attachmentsobject

Any attachments that are associated with the story. See the story attachment node reference for attachments fields.

backdated_timeint

The backdated time for backdate post. For regular post, this field will be set to null.

call_to_actionobject

The call to action type used in any Page posts for mobile app engagement ads.

contextobject

The call to action type used in any Page posts for mobile app engagement ads.

can_reply_privatelyboolean

Whether the Page viewer can send a private reply to this Post. Requires the read_page_mailboxes permission.

caption

Deprecated for Page posts for v3.3+. Use attachments{title} instead.

string

Link caption in post that appears below name. The caption must be an actual URLs and should accurately reflect the URL and associated advertiser or business someone visits when they click on it.

child_attachmentsobject

Sub-shares of a multi-link share post.

created_timedatetime

The time the post was initially published. For a post about a life event, this will be the date and time of the life event.

description

Deprecated for Page posts for v3.3+. Use attachments{description} instead.

string

A description of a link in the post (appears beneath the caption).

feed_targetingobject

Object that controls news feed targeting for this post. Anyone in these groups will be more likely to see this post, others will be less likely, but may still see it anyway. Any of the targeting fields shown here can be used, none are required (applies to Pages only).

age_maxint

Maximum age

age_minint

Must be 13 or higher. Default is 0

citiesint

Values of targeting cities. Use type of adcity to find Targeting Options and use the returned key to specify.

college_yearsint

Array of integers for graduation year from college.

countriesstring

Values of targeting countries. You can specify up to 25 countries. Use ISO 3166 format codes.

education_statusesint

Array of integers for targeting based on education level. Use 1 for high school, 2 for undergraduate, and 3 for alum (or localized equivalents).

gendersint

Target specific genders. 1 targets all male viewers and 2 females. Default is to target both.

interested_in

Deprecated.

intIndicates targeting based on the 'interested in' field of the user profile. You can specify an integer of 1 to indicate male, 2 indicates female. Default is all types. Please note 'interested in' targeting is not available in most European countries and Canada due to local laws.
interestsint

One or more IDs of pages to target fans of pages. Use type of page to get possible IDs as Targeting Options and use the returned id to specify.

localesint

Targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.

regionsarray

Values of targeting regions. Use type of adregion to find Targeting Options and use the returned key to specify.

relationship_statusesint

Array of integers for targeting based on relationship status. Use 1 for single, 2 for 'in a relationship', 3 for married, and 4 for engaged. Default is all types.

from

object

The name and id of the Page, group, or event that created the post. If you read this field with a User access token, it returns only the current user.

full_picturestring

URL to a full-sized version of the Photo published in the Post or scraped from a link in the Post. If the photo's largest dimension exceeds 720 pixels, it will be resized, with the largest dimension set to 720.

iconstring

A link to an icon representing the type of this post.

instagram_eligibilityenum{}

Whether the post can be promoted on Instagram. It returns the enum eligible if it can be promoted. Otherwise it returns an enum for why it cannot be promoted: ineligible_caption_mentions_not_allowed, ineligible_caption_too_long, ineligible_media_aspect_ratio, ineligible_media_dimension, ineligible_media_square_aspect_ratio, ineligible_media_square_dimension, ineligible_post_type, ineligible_unknown_error, or ineligible_video_length.

is_eligible_for_promotionboolean

Indicates whether a post is eligible for promotion.

is_hiddenboolean

If this post is marked as hidden (Applies to Pages only). Hiding a post hides it in a Page's timeline however it is still visible in other places on Facebook, i.e., a link.

is_instagram_eligiblestring

Whether this post can be promoted in Instagram.

is_publishedboolean

Indicates whether a scheduled post was published (applies to scheduled Page Post only, for users post and instantly published posts this value is always true). Note that this value is always false for page posts created as part of the Ad Creation process.

link

Deprecated for Page posts for v3.3+.

Use attachments{url_unshimmed} instead.

string

The link attached to this post.

messagestring

The status message in the post.

message_tagsarray

An array of profiles tagged in the message text. If you read this field with a user User access token, it returns only the current user.

lengthint

The length of the tag text, in unicode code points.

idstring

ID of the profile that was tagged.

namestring

The text used to tag the profile.

offsetint

The location in unicode code points of the first character of the tag text in the message.

typeenum{}

The tagged profile's type, user, page, or group.

name

Deprecated for Page posts for v3.3+.

Use attachments{title} instead.

string

The name of the link.

object_id

Deprecated for Page posts for v3.3+.

Use attachments{target{id}} instead.

string

The ID of any uploaded photo or video attached to the post.

parent_idstring

The ID of a parent post for this post, if it exists. For example, if this story is a 'Your Page was mentioned in a post' story, the parent_id will be the original post where the mention happened.

permalink_urlstring

The permanent static URL to the post on www.facebook.com. Example: https://www.facebook.com/FacebookForDevelopers/posts/10153449196353553.

picturestring

URL to a resized version of the Photo published in the Post or scraped from a link in the Post. If the photo's largest dimension exceeds 130 pixels, it will be resized, with the largest dimension set to 130.

placestring

ID of the

place

associated with this post.

privacyobject

The privacy settings of the post.

allowstring

If value is CUSTOM, this is a comma-separated ID list of users and friendlists (if any) that can see the post.

denystring

If value is CUSTOM, this is a comma-separated ID list of users and friendlists (if any) that cannot see the post.

descriptionstring

Text that describes the privacy settings, as they would appear on Facebook.

friendsenum{}

If value is CUSTOM, this indicates which group of friends can see the post. Values inlcude ALL_FRIENDS, FRIENDS_OF_FRIENDS, or SOME_FRIENDS.

valueenum{}

The actual privacy setting. Values include EVERYONE, ALL_FRIENDS, FRIENDS_OF_FRIENDS, SELF, or CUSTOM.

promotable_idstring

ID of post to use for promotion for stories that cannot be promoted directly.

promotion_eligibility

Deprecated. See is_eligible_for_promotion.

boolean

Indicates whether a post is eligible for promotion.

promotion_status

Deprecated. See is_eligible_for_promotion.

stringStatus of the promotion. Requires Page admin privileges. Possible values:
activePromotion is currently running.
draftPromotion is still in draft mode.
extendablePromotion's campaign has ended but can be restarted.
finishedPromotion has ended.
inactiveNo active promotion.
ineligible

Post is ineligible for boosting. Learn why the post may be ineligible.

pausedPromotion is currently paused.
pendingPromotion is still under review.
rejectedPromotion was rejected by the review process.
propertiesobject

A list of properties for any attached video, for example, the length of the video.

namestring

The property name.

textstring

The value of the property.

hrefstring

Any link associated with the property.

sharesobject

The share count of this post. The share count may include deleted posts and posts you cannot see for privacy reasons.

source

Deprecated for Page posts for v3.3+.

Use attachments{media{source}} instead.

string

A URL to any Flash movie or video file attached to the post.

status_typeenum{}

The type of a status update. Values include mobile_status_update, created_note, added_photos, added_video, shared_story, created_group, created_event, wall_post, app_created_story, published_story, tagged_in_photo, or approved_friend.

targetingobject

Object that limits the audience for this content. Only audiences in the specified demographics can view this content. The demographics are additive. Each additional value adds its audience to the cumulative targeted audience. These values do not override any Page-level demographic restrictions that may be in place.

countriesstring

Values of targeting countries as ISO 3166 format codes.

localesint

Targeted locales. Targeting Options of the type adlocale may be returned.

regionslist<int>

Values for targeted regions. Targeting Options of the type adregion may be returned.

citieslist<int>

Values for excluded cities. Targeting Options of the type adcity may be returned.

to

object

Profiles mentioned or targeted in this post. If you read this field with a user access token, it returns only the current user.

type

Deprecated for Page posts for v3.3+.

Use attachments{media_type} instead. If there is no attachments or media_type=link, the value is the same as type=status.

enum{}

A string indicating the object type of this post. enum values include link, status, photo, video, and offer.

updated_timedatetime

The time the post was last updated, which occurs when the post was created, edited, or a user comments on a post, expressed as a UNIX timestamp.

with_tags

object

Profiles tagged as being with the publisher of the post. If you read this field with a user access token, it returns only the current user.

Publishing

You can publish posts by using the /user-id/feed, /page-id/feed, /event-id/feed, or /group-id/feed edges.

When creating a Post for a Page if you use a User access token the Post will be in the voice of the User that posted it. If you use a Page access token, the Post will be in the voice of the Page.

Deleting

An app can delete any post it published, or a page-management app can delete a Post published to a Page that the app manages.

DELETE /v3.3/post-id HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->delete(
    '/post-id',
    array (),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/post-id",
    "DELETE",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/post-id",
    null,
    HttpMethod.DELETE,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/post-id"
                                      parameters:params
                                      HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • To delete a Page's post a Page access token and publish_pages permission is required.
  • To delete a User's post on Page a Page access token is required.
  • To delete another User's post on a Page-owned event the user_managed_groups permission is required.

Fields

No fields are required.

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Updating

An app can update a Post object:

POST /v3.3/post-id HTTP/1.1
Host: graph.facebook.com

message=This+is+a+test+message
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/post-id',
    array (
      'message' => 'This is a test message',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/post-id",
    "POST",
    {
        "message": "This is a test message"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("message", "This is a test message");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/post-id",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"message": @"This is a test message",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/post-id"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

As of April 24,2018, the publish_actions permission has been removed. Please see the Breaking Changes Changelog for more details. To provide a way for your app users to share content to Facebook, we encourage you to use our Sharing products instead.

Limitations

An app can update a post only if it was the one that published it.

Fields

An app can only update a limited set of fields on a Post object. The fields an app can update are:

  • message
  • tags
  • privacy (Not available for Page posts.)

Response

If successful, you will receive a response with the following information. In addition, this endpoint supports read-after-write and can immediately return any fields returned by read operations.

{
  "success": true
}

If unsuccessful, a relevant error message will be returned.

Edges

Name Description

/comments

Comments on this post.

/insights

Insights for this post (Posts on Pages only).

/likes

People who like this post.

/private_replies

Reply to this Visitor Post (only) with a private Message.

/reactions

People who have reacted to this post.

/sharedposts

Shares of this post.