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 /v2.7/{post-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{post-id}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* 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

  • Any valid access token can read posts on a public Page.
  • A page access token can read all posts posted to or posted by that Page.
  • A user access token can read any post your application created on behalf of that user.
  • A user's post can be read if the owner has granted the user_posts permission.
  • A user access token may read a post that user is tagged in if they have granted the user_posts permission. However, in some cases the post's owner's privacy settings may not allow your application to access it.

Fields

NameDescriptionType

id

The post ID

string

admin_creator

ID of admin, app or business that created the post. Applies to pages only

object[]

id

ID of the person, app or business

int

name

Name of the person, app or business

string

application

Information about the app this post was published by.

App

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

caption

The caption of a link in the post (appears beneath the name).

string

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 about the profile that posted the message.

Profile

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. Although visitor's post on Page can not be approved using this field).

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 instanlty published posts this value is always true)

boolean

link

The link attached to this post.

string

message

The status message in the post.

string

message_tags

Profiles tagged in message. This is an object with a unique key for each tag in the message

object

{tag-key}

Each tag in the message has a unique key within the message_tags object, which also indicates the order in which it appears in the message. The corresponding value of this key is another object representing the tag itself.

object

id

ID of the profile that was tagged.

string

name

The text used in the tag.

string

type

Indicates which type of profile is tagged.

enum{user, page, group}

offset

Where the first character of the tagged text is in the message, measured in unicode code points.

integer

length

How many unicode code points this tag consists of, after the offset.

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

picture

The picture scraped from any link included with the post.

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>

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>

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.

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

Text from stories not intentionally generated by users, such as those generated when two people become friends, or when someone else posts on the person's wall.

string

story_tags

Deprecated field, same as message_tags.

array

targeting

Object that limited the audience for this content. Anyone not in these demographics will not be able to view this content. This will 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>

cities

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

list<unsigned int32>

to

Profiles mentioned or targeted in this post.

Profile[]

type

A string indicating the object type of this post.

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

updated_time

The time when the post was created, last edited or the time of the last comment that was left on the post.

For a post about a life event, this will be the date and time of the life event

datetime

with_tags

Profiles tagged as being 'with' the publisher of the post.

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 /v2.7/{post-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'DELETE',
  '/{post-id}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* 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 user's post, a user access token with publish_actions permission is required.
  • 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.

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 if it published it. For fields other than the link field, use the following syntax:

POST /v2.7/{post-id} HTTP/1.1
Host: graph.facebook.com

message=This+is+a+test+message
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'POST',
  '/{post-id}',
  array (
    'message' => 'This is a test message',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* 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

  • A user access token with publish_actions permission.

Fields

You can update any of the fields, except link, listed in the Publishing sections of the /{user-id}/feed, /{page-id}/feed, /{event-id}/feed, or /{group-id}/feed edges.

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Edges

NameDescription

/likes

People who like this post.

/reactions

People who have reacted to this post.

/comments

Comments on this post.

/sharedposts

Shares of this post.

/insights

Insights for this post (only for Pages).

/attachments

All media attachments associated with this post.