This document refers to an outdated version of Graph API. Please use the latest version.
Graph API Version

/{page-id}/feed

The feed of posts (including status updates) and links published by this page, or by others on this page. There are other edges which provide more specific sets of posts:

  • /{page-id}/posts shows only the posts that were published by this page.
  • /{page-id}/tagged shows all public posts in which the page has been tagged.
  • /{page-id}/promotable_posts shows only the posts that can be boosted (includes unpublished and scheduled posts).

These edges share the same reading structure, however /feed should be used for all publishing purposes. They all have an upper boundary for the limit parameter of 100 posts. Specifying any higher limit will throw an error.

Related Guides

Reading

Graph API Explorer
GET /v2.9/{page-id}/feed HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{page-id}/feed'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/feed",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/feed",
    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:@"/{page-id}/feed"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • An access token is required to view publicly shared posts.
  • A user access token is required to retrieve posts visible to that person.
  • A page access token is required to retrieve any other posts.
  • A user access token with ads_management permission or a page access token is required for /{page-id}/promotable_posts.

Limitations

You can only read a maximum of 100 feed posts with the limit field. If you try to read more than that you will get an error message to not exceed 100.

When you use /{page-id}/tagged to show the posts that tag this page, the results include posts from other pages only if those pages are authentic.

The available user agents allowed for these Graph API calls are subject to change without notice. If you are experiencing issues, you may want to change to a newer version of your particular user agent.

Fields

An array of Post objects.

Modifiers

NameDescriptionType

include_hidden

Include posts hidden by the Page. Can only be used with the /{page-id}/feed edge. Defaults to false

bool

filter

This field is deprecated.

include_inline

Used with the promotable_posts edge only. Filters by whether the post was created inline via object_story_spec in the Ads API. This used to be called is_inline

bool

is_published

Used with the promotable_posts edge only. Filters by published or unpublished page posts.

bool

Publishing

You can create links, status messages, or posts by using this edge:

POST /v2.9/{page-id}/feed 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',
  '/{page-id}/feed',
  array (
    'message' => 'This is a test message',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/feed",
    "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(),
    "/{page-id}/feed",
    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:@"/{page-id}/feed"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A user access token with publish_actions permission can be used to publish new posts on behalf of that person. Posts will appear in the voice of the user.
  • A page access token with publish_pages permission can be used to publish new posts on behalf of that page. Posts will appear in the voice of the page.

Fields

NameDescriptionType

message

The main body of the post, otherwise called the status message. Either link or message must be supplied. The message can contain mentions of Facebook Pages using the following syntax:

@[page-id]

For example the following message would mention the Facebook Developers page inline:

Test message @[19292868552] tag

Usage of this feature is subject to review but by using Pages you are an admin of (both to make the API call, and to be used in a mention), and an app you are a developer of, you can test it for yourself before review.

string

link

The URL of a link to attach to the post. Either link or message must be supplied. Additional fields associated with link are shown below.

string

actions

The action links attached to the post.

array[]

name

The name or label of the action link.

string

link

The URL of the action link itself.

string

place

Page ID of a location associated with this post.

string

tags

Comma-separated list of user IDs of people tagged in this post. You cannot specify this field without also specifying a place.

csv[string]

object_attachment

Facebook ID for an existing picture in the person's photo albums to use as the thumbnail image. They must be the owner of the photo, and the photo cannot be part of a message attachment.

string

targeting

Object that limits 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

geo_locations

This object allows you to specify a number of different geographic locations. Please see our targeting guide for information on this object.

object

locales

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

int[]

feed_targeting

Object that controls news feed targeting for this content. Anyone in these groups will be more likely to see this content, those not will be less likely, but may still see it anyway. Any of the targeting fields shown here can be used, none are required.

object

geo_locations

This object allows you to specify a number of different geographic locations. Please see our targeting guide for information on this object.

object

age_min

Must be 13 or higher. Default is 0

int

age_max

Maximum age. Must be 65 or lower.

int

genders

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

list<unsigned int32>

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.

list<unsigned int32>

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.

list<unsigned int32>

college_years

Array of integers for graduation year from college.

int[]

interests

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

int[]

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[]

locales

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

int[]

published

Whether a story is shown about this newly published object. Default is true which means the story is displayed in News Feed. This field is not supported when actions parameter is specified. Unpublished posts can be used in ads.

bool

scheduled_publish_time

Time when this post should go live, this can be any date between ten minutes and six months from the time of the API call.

timestamp

backdated_time

Specifies a time in the past to back-date this post to.

timestamp

backdated_time_granularity

Controls the display of how a backdated post appears. For example, if you pick month posts will be displayed as 2 months ago. instead of an exact date.

enum{year, month, day, hour, minute}

child_attachments

Use to specify multiple links in the post. Minimum 2 and maximum of 5 objects. If you set multi_share_optimized to true, you can upload a maximum of 10 objects but Facebook will display the top 5

array of link objects

link

The URL of a link to attach to the post. This field is required.

string

picture

Determines the preview image associated with the link (1:1 aspect ratio and a minimum of 458 x 458 px for best display). Either picture or image_hash must be specified.

URL

image_hash

hash of a preview image associated with the link from your ad image library (1:1 aspect ratio and a minimum of 458 x 458 px for best display). Either picture or image_hash must be specified.

string

name

The title of the link preview. If not specified, the title of the linked page will be used. This field will typically be truncated after 35 characters. It is recommended to set a unique name, as Facebook interfaces will show actions reported on the name field.

string

description

Used to show either a price, discount or website domain. If not specified, the content of the linked page will be extracted and used. This field will typically be truncated after 30 characters.

string

video_id

ID of a video from the same page, can be used in any of the children. If specified, must also set image_hash or picture to serve as the video thumbnail.

numeric string

multi_share_optimized

If set to true and only when the post is used in an ad, Facebook will automatically select the order of links in child_attachments. Otherwise, the original ordering of child_attachments is preserved. Default value is true.

boolean

multi_share_end_card

If set to false, does not display the end card of a carousel link post when child_attachments is used. Default is true.

boolean

Response

If successful, the ID of the post will be returned as part of a JSON response. In addition, this endpoint supports read-after-write and can immediately return any fields returned by read operations.

{"id":"1223482973892_2871279817289"}

Deprecated Fields

As of April 18, 2017, the following parameters are no longer supported by Graph API versions 2.9 and higher. For versions 2.8 and lower, the parameters will continue working until July 17, 2017.

NameDescriptionType

link

The link field is still supported, but its sub-fields have been deprecated.

string

picture

Determines the preview image associated with the link.

string

name

Overwrites the title of the link preview.

string

caption

Overwrites the caption under the title in the link preview.

string

description

Overwrites the description in the link preview

string

Deleting

You can't delete using this edge, however you can delete posts using the /{post-id} node.

Updating

You can't update using this edge, however you can update posts using the /{post-id} node.

Unpublished Page Posts

We support the following types of Unpublished Page Posts:

Post TypeDescription

Status Post

a status page post with a text description

Photo post

a photo page post with a text description and an optional link as part of the description

Link post

A link Page post is most effective for sharing links to your website. Allows for optional replacement of image and extra text.
Note: A Youtube video link will be a link page post

Video post

a video page post with optional text description

Offer post

a page post that allows you to promote deals for your store. This can only be for a offline offer, online offers are no longer supported.

Unpublished Page Posts are treated the same as published page posts except that they appear only on the page's /promotable_posts connection (and not /feed).

To see the list of promotable, unpublished page posts, use the is_published field when searching as shown in the following URL:

curl https://graph.facebook.com/<API_VERSION>/204807582871020/promotable_posts?fields=id&is_published=false

Please refer to the page feed documentation for a description of the response fields.

To view a post on Facebook.com, you can navigate to https://www.facebook.com/<POST_ID> for most post types, or retrieve the actions field of the post, which contains the URL at which a user can like or comment on the post.

Page Post call_to_action

You can enhance your link page posts with call to action buttons. The following call_to_action field can be added to new link Page Posts.

NameDescriptionType

call_to_action

Object that specifies a Call to Action button. This should be the action you want people to take when they see your post. Clicking on this button will take people to the link you specify.

object

type

Determines the call to action button text. One of allowed values:

BOOK_TRAVEL. Call to action shows up as Book Now.

BUY_NOW. Call to action shows up as Buy Now. Only used for desktop app ads for virtual goods.

CALL_NOW. Call to action shows up as Call Now. Only used for local awareness ads.

DOWNLOAD. Call to action shows up as Download.

GET_DIRECTIONS. Call to action shows up as Get Directions. Must specify coordinates on the link field. Only used for local awareness ads.

GET_QUOTE. Call to action shows up as Get Quote for lead generation.

INSTALL_APP. Call to action shows up as Install Now.

INSTALL_MOBILE_APP. Call to action shows up as Install Now. Only used for mobile app ads.

LEARN_MORE. Call to action shows up as Learn More.

LIKE_PAGE. Call to action shows up as Like Page. Only used for ads in Page Likes objective.

LISTEN_MUSIC. Call to action shows up as Listen Music.

MESSAGE_PAGE. Call to action shows up as Send Message. Only used for local awareness ads.

NO_BUTTON. No call to action shows up.

OPEN_LINK. Call to action shows up as Open Link. Only used for ads in Website Clicks objective.

PLAY_GAME. Call to action shows up as Play Game. Only used for desktop app ads.

SHOP_NOW. Call to action shows up as Shop Now. Only used for ads in Website Conversions objective.

SIGN_UP. Call to action shows up as Sign Up.

SUBSCRIBE. Call to action shows up as Subscribe for lead generation.

USE_APP. Call to action shows up as Use App.

USE_MOBILE_APP. Only used for mobile app ads.

WATCH_MORE. Call to action shows up as Watch More.

WATCH_VIDEO. Call to action shows up as Watch Video.

string

value

Supporting data for the Call to Action button

object

link

URL that the Call to Action button will link to. For link page post this must be the same as the link value of the post. Only external shares are allowed. The CTA link cannot link to facebook.com/.. but can link to apps.facebook.com/app-id.. and other external links.
When Call to Action button is GET_DIRECTIONS or CALL_NOW, link format differs. Please refer to local awareness docs for more detail.

string

link_caption

Specifies the caption used for the link which appears below the description. Default is the host name from the link. For example www.example.com. Overwrites captions specified in other fields.

string

link_format

Specifies the format for the link. For example VIDEO_LPP for video page posts with call to action.

string

link_title

Used in carousel ads and is the title of the link of an individual story within the child_attachment.

string

page

Page ID when type is LIKE_PAGE

string

Custom link page post image

As of April 18, 2017, these parameters are no longer supported by Graph API versions 2.9 and higher. For versions 2.8 and lower, the parameters will continue working until July 17, 2017.

When creating a link page post, the story's attachment will render an image retrieved from the link. Currently it is possible to override that image by providing an optional picture parameter with a URL to a new image. The thumbnail parameter offers similar functionality with the key difference being that the parameter accepts a local image file which is uploaded to Facebook in the API call:

ParametersTypeDescriptionExpectation

No optional image parameters

Image is sourced from the contents of the Link

picture parameter supplied

string

URL for the image

Image is sourced from the URL supplied in picture

name parameter supplied

string

The name of the link attachment.

Name is sourced from string supplied

caption

string

The caption of the link (appears beneath the link name).

If not specified, this field is automatically populated with the URL of the link.

description

string

The description of the link (appears beneath the link caption).

If not specified, this field is automatically populated by information scraped from the link, typically the title of the page.

thumbnail parameter supplied

file

Image file to be uploaded. Accepts .jpg .jpeg .gif or .png

Image is sourced from the file uploaded in thumbnail

  • The thumbnail parameter is only available for link posts on Facebook Pages.
  • Since it is only available for Facebook Pages, ensure that the access_token used in the API calls is for a Page and not a User.
  • The thumbnail parameter takes higher precedence over the picture parameter. If both are supplied the picture parameter is unused.
  • The thumbnail parameter accepts images with extension .jpg .jpeg .gif or .png.
  • The thumbnail parameter is not supported in batch requests.

Link Page Post

Image supplied through the API call. The "picture" parameter in the example below is optional, and when it's not provided, Facebook will read the image from the link's meta data.

curl -F 'message=Book your trip to Alaska'\
     -F 'link=http://example.com'\
     -F 'picture=http://imageurl.com/image'\
     -F 'published=0'\
     -F 'access_token=<PAGE_TOKEN>'\
  https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/feed

Return Value

{"id":"<POST_ID>"}

Link Page Post with Call to Action

The call_to_action field specifies the appropriate action and relevant link. This link should be the same as the link parameter of the Page Post. In this call, title, description, caption and picture are optional, and when not provided, Facebook will read the equivalent properties from the link's Open Graph meta data. If the linked web page does not have Open Graph meta data, Facebook will try to guess these properties by scraping the web page's content.

curl -F 'message=Book your trip to Alaska'\
     -F 'link=http://example.com'\
     -F 'name=Alaska Trips'\     
     -F 'description=Unique travel experiences in the last frontier.'\
     -F 'caption=Alaska'\
     -F 'picture=http://imageurl.com/image'\
     -F 'published=0'\
     -F 'call_to_action={"type":"BOOK_TRAVEL","value":{"link":"http://example.com"}}'\
     -F 'access_token=<PAGE_TOKEN>'\
  https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/feed

Return Value

{"id":"<POST_ID>"}

Link post with custom uploaded image

Using a local file:

curl \
  -F 'link=http://www.example.com' \
  -F 'thumbnail=@/local/path/to/file/on/hard/drive/image.jpg' \
  -F 'access_token=<PAGE_TOKEN>'\
  https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/feed

Return Value

{"id":"<POST_ID>"}

Using an image via URL:

curl \
  -F 'link=http://www.example.com' \
  -F 'picture=https://www.example.com/path/to/image.jpg' \
  -F 'access_token=<PAGE_TOKEN>'\
  https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/feed

Return Value

{"id":"<POST_ID>"}

Photo Page Post

curl -F 'message=Book your trip to Alaska, http://bit.ly/alaska'\
     -F 'source=@alaska.jpg'\
     -F 'published=0'\
     -F 'access_token=<PAGE_TOKEN>'\
  https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/photos

Return Value

{"id":"<POST_ID>"}

Video Page Post

curl -F 'name=Alaska'\
     -F 'description=Book your trip to Alaska, http://bit.ly/alaska'\
     -F 'source=@video.mov'\
     -F 'published=0'\
     -F 'access_token=<PAGE_TOKEN>'\
  https://graph-video.facebook.com/<API_VERSION>/<PAGE_ID>/videos

Return Value

{"id":"<POST_ID>"}

Page Post Insights

Related Topics

Unpublished Page Post level metrics and insights can be retrieved same as the regular page posts.

Metrics fetched on the page post will also include organic (non-paid) metrics.

curl https://graph.facebook.com/<API_VERSION>/204807582871020_615180368500404/insights

// sample response:
{
  "data": [
    {
      "id": "204807582871020_615180368500404/insights/post_story_adds_unique/lifetime", 
      "name": "post_story_adds_unique", 
      "period": "lifetime", 
      "values": [
        {
          "value": 2
        }
      ], 
        "title": "Lifetime Talking About This (Post)", 
      "description": "Lifetime The number of unique people who created a story by interacting with your Page post. (Unique Users)"
    }, 
    {
      "id": "204807582871020_615180368500404/insights/post_story_adds/lifetime", 
      "name": "post_story_adds", 
      "period": "lifetime", 
      "values": [
        {
          "value": 2
        }
      ], 
      "title": "Lifetime Post Stories", 
      "description": "Lifetime The number of stories generated about your Page post. (Total Count)"
    }, 
    {
      "id": "204807582871020_615180368500404/insights/post_story_adds_by_action_type_unique/lifetime", 
      "name": "post_story_adds_by_action_type_unique", 
      "period": "lifetime", 
      "values": [
        {
          "value": {
            "like": 2
          }
        }
      ], 
      "title": "Lifetime Talking About This (Post) by action type", 
      "description": "Lifetime The number of unique people who created a story about your Page post by interacting with it. (Unique Users)"
    }, 
    {
      "id": "204807582871020_615180368500404/insights/post_story_adds_by_action_type/lifetime", 
      "name": "post_story_adds_by_action_type", 
      "period": "lifetime", 
      "values": [
        {
          "value": {
            "like": 2
          }
        }
      ], 
            "title": "Lifetime Post Stories by action type", 
      "description": "Lifetime The number of stories created about your Page post, by action type. (Total Count)"
    }, 
    {
      "id": "204807582871020_615180368500404/insights/post_impressions_unique/lifetime", 
      "name": "post_impressions_unique", 
      "period": "lifetime", 
      "values": [
        {
          "value": 6880
        }
      ], 
      "title": "Lifetime Post Total Reach", 
      "description": "Lifetime The number of people who saw your Page post. (Unique Users)"
    }, 
    {
      "id": "204807582871020_615180368500404/insights/post_impressions/lifetime", 
      "name": "post_impressions", 
      "period": "lifetime", 
      "values": [
        {
          "value": 7067
        }
      ], 
      "title": "Lifetime Post Total Impressions", 
      "description": "Lifetime The number of impressions of your Page post. (Total Count)"
    }, 
    ...
}