Graph API
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.2/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

NameDescriptionType
id

The post ID

string
actions

Action links

object
admin_creator

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.

object
id

ID of the person, app or business.

int
name

Name of the person, app or business.

string
allowed_advertising_objects

Objectives under which this post can be advertised

string
application

Information about the app this post was published by.

app
attachments

Any attachments that are associated with the story

object
backdated_time

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

int
call_to_action

The call to action type used in any Page posts for

mobile app engagement ads

.

object
context

The call to action type used in any Page posts for

mobile app engagement ads

.

object
can_reply_privately

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

boolean
caption

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.

string
child_attachments

Sub-shares of a multi-link share post.

object
created_time

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.

datetime
description

A description of a link in the post (appears beneath the

caption

).

string
feed_targeting

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).

object
age_max

Maximum age

int
age_min

Must be 13 or higher. Default is 0

int
cities

Values of targeting cities. Use

type

of

adcity

to

find Targeting Options

and use the returned

key

to specify.

int[]
college_years

Array of integers for graduation year from college.

int[]
countries

Values of targeting countries. You can specify up to 25 countries. Use

ISO 3166 format codes

.

string[]
education_statuses

Array of integers for targeting based on education level. Use

1

for high school,

2

for undergraduate, and

3

for alum (or localized equivalents).

int[]
genders

Target specific genders.

1

targets all male viewers and

2

females. Default is to target both.

int[]
interested_in

Indicates 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 France due to local laws.

int[]
interests

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.

int[]
locales

Targeted locales. Use

type

of

adlocale

to

find Targeting Options

and use the returned

key

to specify.

int[]
regions

Values of targeting regions. Use

type

of

adregion

to

find Targeting Options

and use the returned

key

to specify.

adregion[]
relationship_statuses

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.

int[]
from

Information (name and id) about the Profile that created the Post. If you read this field with a user access token, it returns only the current user.

object

full_picture

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.

string

icon

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

string
instagram_eligibility

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.

string
is_hidden

If this post is marked as hidden (Applies to Pages only).

boolean
is_instagram_eligible

Whether this post can be promoted in Instagram.

string
is_published

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.

boolean
link

The link attached to this post.

string
message

The status message in the post.

string
message_tags

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.

array
id

ID of the profile that was tagged.

string
name

The text used to tag the profile.

string
type

The tagged profile's type.

enum{user, page, group}
offset

The location in

unicode code points

of the first character of the tag text in the

message

.

integer
length

The length of the tag text, in

unicode code points

.

integer
name

The name of the

link

.

string
object_id

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

string
parent_id

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.

string
permalink_url

URL to the permalink page of the post.

string
picture

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.

string
place

Any location information attached to the post.

Place
privacy

The privacy settings of the post.

object
description

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

string
value

The actual privacy setting.

enum{EVERYONE, ALL_FRIENDS, FRIENDS_OF_FRIENDS, SELF, CUSTOM}
friends

If

value

is

CUSTOM

, this indicates which group of friends can see the post.

enum{ALL_FRIENDS, FRIENDS_OF_FRIENDS, SOME_FRIENDS}
allow

If

value

is

CUSTOM

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

csv<string&gt;
deny

If

value

is

CUSTOM

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

csv<string&gt;
promotable_id

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

string
promotion_status

Status of the promotion. Requires Page admin privileges. Possible values:

string
active

— Promotion is currently running.

draft

— Promotion is still in draft mode.

extendable

— Promotion's campaign has ended but can be restarted.

finished

— Promotion has ended.

inactive

— No active promotion.

ineligible

— Post is ineligible for boosting.

Learn why the post may be ineligible.
paused

— Promotion is currently paused.

pending

— Promotion is still under review.

rejected

— Promotion was rejected by the review process.

properties

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

object[]
name

The property name.

string
text

The value of the property.

string
href

Any link associated with the property.

string
shares

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

object
source

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

string
status_type

Description of the type of a status update.

enum{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, approved_friend}
story

Deprecated

string
story_tags

Deprecated field, same as

message_tags

.

array
targeting

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.

object
countries

Values of targeting countries as

ISO 3166 format codes

.

string[]
locales

Targeted locales.

Targeting Options

of the type

adlocale

may be returned.

int[]
regions

Values for targeted regions.

Targeting Options

of the type

adregion

may be returned.

list<unsigned int32&gt;
cities

Values for excluded cities.

Targeting Options

of the type

adcity

may be returned.

list<unsigned int32&gt;
to

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

Profile[]
type

A string indicating the object type of this post.

enum{link, status, photo, video, offer}
updated_time

This field's behavior depends on the type of object the Post is on:

datetime

Group Posts — Time when the Post was created or commented upon.

Page Posts — Time when the Post was created, edited, or commented upon.

User Posts — Time when the Post was created, edited, or commented upon.

with_tags

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.

JSON object with a

data

field that contains a list of

Profile objects.

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.2/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_pagespermission 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.2/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.

  • A user access token with publish_actionspermission.

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.