Common Uses

The Graph API is a powerful resource which can be used in a variety of ways. This doc provides a list of common scenarios for apps, an example to get you started, and reference docs to help you build solutions. Visit our Using the API Guide and our reference docs for the technical structure, fields, and operations available in the API.

Get an Access Token

Access tokens are random strings giving you temporary secure access to our APIs. These tokens include permissions for specific social graph data such as a User's name or age. The best way to get access tokens is to implement Facebook Login. If you are using a Facebook SDK, Facebook Login is already included.

To learn how to get an access token, please visit our Access Token Guide.

Convert to a Long-lived Token

In some instances you may need a long-lived access token. Convert a short-lived token to a long-lived one.

Examples

The request:

GET /oauth/access_token  
  ?grant_type=fb_exchange_token           
  &client_id=app-id
  &client_secret=app-secret
  &fb_exchange_token=short-lived-token

Docs

Get Data About Me or Others

Getting information about you or other Facebook Users is an identical process; all that is needed is a User's Facebook ID.

Node

Permissions

Examples

Send a GET /id request, where id is either your user-id or another person's user-id, asking for About and Birthday information using an access token with user_about_me and user_birthday permissions.

The Request

GET https://graph.facebook.com/v2.11
  /user-id 
    ?fields=id,name,about,birthday 
    &access_token=user-access-token

The Response

{
  "id": "john's-user-id",
  "name": "John Pants",
  "about": "This is all about me.",
  "birthday": "01/01/1985"
}

If information is missing from the response the User may not have filled out those fields or a permission is missing.

Docs

Facebook Friends

Due to privacy restrictions, you are only able to get a list of Users who have installed your app, not a complete Friend list. You can get a total count of all Friends which includes those who have not installed your app.

Edges

Access Token

  • User access token with user_friends permissions

Examples

Send a GET /id/friends request, where id is a user-id, to get a list of friends who have installed the app and the total number of Friends.

The Request

GET https://graph.facebook.com/v2.11
  /id 
    /friends 
    &access_token=user-access-token

The response:

{
  "data": [
    {
      "name": "Julia Goulia",
      "id": "julia's-user-id"
    },
    {
      "name": "Steven Even",
      "id": "steven's-user-id"
    }
        ],
  "summary": {
    "total_count": 156
  }
}

Docs

Publish A New Status Update

Apps can create new status updates on behalf of people or Facebook Pages.

Endpoints

Access Token

  • User access token with publish_actions permissions to post on behalf of that user.

As of April 24,2018, the pubish_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.

  • Page access token with manage_pages and publish_pages permissions to post as an admin of that page.

Examples

Send a POST /id/feed request where id is a user-id to post to a User's Feed or a page-id to post to a Page.

The Request

POST graph.facebook.com/v2.11
  /id/feed
    ?message=Hello World!
    &access_token=access-token

The Response

{
  "id": "post-id"
}

Docs

Set Privacy When Publishing

Most endpoints allowing you to post (e.g. posts, photos, notes) also allow you to include a privacy parameter. This parameter controls who can see the post. If it is not supplied, it defaults to the privacy level granted to the app in the Login Dialog. This parameter cannot be used to set a more open privacy setting than the one granted during login.

What's passed to the privacy parameter is actually a JSON-encoded object. It contains the following fields:

Name Description Type

value

The value of the privacy setting.

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

allow

When value is CUSTOM, this is a comma-separated list of user IDs and friend list IDs that can see the post. This can also be ALL_FRIENDS or FRIENDS_OF_FRIENDS to include all members of those sets.

string|csv[string]

deny

When value is CUSTOM, this is a comma-separated list of user IDs and friend list IDs that cannot see the post.

string|csv[string]

Example

Send a POST /id/feed request with with privacy set.

The Request

POST graph.facebook.com/v2.11
  /id/feed
    ?message=Hello World!
    &privacy={'value':'ALL_FRIENDS'}
    &access_token=access-token

The Response

{
  "id": "post-id"
}

Apps can share links to content on other websites on behalf of people or Facebook Pages.

The Edges

Access Tokens

  • User access token with publish_actions permissions for a User to share a link.

As of April 24,2018, the pubish_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.

  • Page access token with manage_pages and publish_pages permissions for a Page admin sharing a link on a page.

Examples

  • Send a POST /id/feed request where id is page-id or user-id and add the link field with value of a url.

The Request

POST graph.facebook.com/v2.11
  /id/feed
    ?link=https://www.facebook.com/
    &access_token=access-token

The Response

{
"id": "post-id"
}

Docs

Get Share Counts

Find how many times a url has been shared on Facebook.

Nodes

Access Token

  • Any valid access token if the link is public.
  • User access token with read_stream permission for any other links.

Examples

Send a GET /id request, where id is the link id, with the engagement field's share_count parameter.

The Request

GET https://graph.facebook.com/v2.11
  /url 
    ?fields=engagement{share_count} 
    &access_token=user-access-token

The Response

{
  "share_count": 156
}

Docs

Upload Photos and Videos and Create Photo Albums

Apps are able to create and publish new photo Albums, and publish photos or videos via the Graph API on behalf of people or Facebook Pages.

  • Photos can be uploaded by sending the actual image files or by using image URLs.
  • Videos can be uploaded as part of a chunked, resumable upload. For more information, see Video Upload with Graph API.

Create an Album

The Edges

Access Token

As of April 24,2018, the pubish_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.

  • User access token with publish_actions and user_photos permissions for a user creating a user album.
  • User access token with user_photos, publish_actions and user_managed_groups permissions for a user creating a group album.
  • Page access token with manage_pages and publish_pages permissions for a page admin to create a page album.
  • App access token can be used for a person who has already granted user_photos, publish_actions and user_managed_groups permissions for creating a group album using your app.

Examples

Create a POST /id/albums request where id is the user-id, page-id, or event-id and set name to the name of your Album.

The Request

POST graph.facebook.com/v2.11
  /id/albums
    ?name=My New Album
    &access_token=user-access-token

The Response

{
  "id": "album-id"
}

Docs

Post a Photo

The Edges

Access Token

  • Posting to a User or Album requires a User access token with publish_actions and user_photos permissions.

As of April 24,2018, the pubish_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.

  • Posting a photo to a Page requires a Page access token with manage_pages and publish_pages permissions. You must also be a Page admin of a Page to post to it.

Examples

Create a POST /id/photos request where id can be an album-id, page-id, or user-id.

The Request

POST graph.facebook.com/v2.11
  /id/photos
    ?url=http://crumbavenue.com/assets/tutorials/steps/437/large/crumb-avenue-cute%20unicorn-20150705173143.jpg
    &access_token=user-access-token

The Response

{
  "id": "photo-id"
  "post_id": "post-id"
}

The Docs

Uploading a Video

The Edges

Access Tokens

  • User access token with publish_action permissions

As of April 24,2018, the pubish_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.

  • Page access token with manage_pages and publish pages for a page admin of the Page

Examples

Create a POST /id/videos request where id can be an event-id, group-id, page-id, or user-id.

The Request

POST graph.facebook.com/v2.11
  /id/videos
    ?field=value
    &access_token=user-access-token

The Response

{
  "id": "video-id"
  "post_id": "post-id"
}

Docs

Posting Videos

The Edges

  • to post an event's videos.
  • to post a page's videos.
  • to post a user's videos.

Access Tokens

  • User access token with publish_action and user_videos permissions

As of April 24,2018, the pubish_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.

  • Page access token with manage_pages and publish pages for a Page admin of the Page

Examples

Create a POST /id/videos request where id can be an event-id, group-id, page-id, or user-id.

The Request

POST graph.facebook.com/v2.11
  /id/videos
    ?field=value
    &access_token=user-access-token

The Response

{
  "id": "video-id"
  "post_id": "post-id"
}

Docs

Respond to an Event

Apps can respond to events on behalf of people.

Endpoints

Access Tokens

  • User Access Token with user_events and rsvp_event permissions.

Examples

Send a POST /id/rvsp-status request where id is an event-id and rvsp-status is set to attending, maybe, or declined.

The Request

POST graph.facebook.com/v2.11
  /id/attending
    ?access_token=access-token

The Response

{
  "success": "true"
}

Docs

Create Content without Publishing

It is possible to add content to the Graph without publishing to Newsfeed or a Profile Story. This is useful in a few situations, such as Page posts which are scheduled to go live at a particular time, or when a photo is to be used in a photo comment.

Endpoints

Access Token

  • User access token with publish_actions permissions to post on behalf of that User.

As of April 24,2018, the pubish_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.

  • Page access token with manage_pages and publish_pages permissions to post as an admin of that Page.

Examples

Send a POST /id/feed request where id is a user-id or page-id and the published field is set to false.

The Request

POST graph.facebook.com/v2.11
  /id/feed
    ?message=Hello World!
    &published=false
    &access_token=access-token

The Response

{
  "id": "post-id"
}

Docs

Scheduling Posts for Pages

Facebook Page posts can be scheduled to go live at a particular time. The scheduled_publish_time parameter should be included when publishing a Page post, and it should be a UNIX timestamp that is between 10 minutes and 6 months from the time of publish. You can update this scheduled time by updating the post with a new scheduled_publish_time.

Edges

/page-id/feed

Access Tokens

  • Page access token with manage_pages and publish_pages for a page admin posting to a page.

Examples

Send a POST /id/feed request where id is a page-id, the published field is set to false, and scheduled_publish_time is a UNIX timestamp.

The Request

POST graph.facebook.com/v2.11
  /id/feed
    ?message=A scheduled post
    &published=false
    &scheduled_publish_time=1429134465
    &access_token=access-token

The Response

{
  "id": "post-id"
}

Docs

Backdating Content

It is also possible to back-date Page posts using the Graph API. This involves updating an existing post with a new date.

Edges

Access Tokens

  • Page access token with manage_pages and publish_pages for a page admin posting to a page.

Examples

An Existing Post

First you must get the post-id of the post you want to backdate by send a get request to the Page Feed edge with an access token with user_posts permissions.

The Request

GET graph.facebook.com/v2.11
  /id/feed
    ?access_token=access-token

Select the post-id you need.

Send a POST /id request where id is the post-id of the post to be backdate.

The Request

POST graph.facebook.com/v2.11
  /id
    ?backdated_time=1429134465
    &access_token=access-token

The Response

{
  "success": true
}

Docs

Page Insights

Access metrics about your Facebook Page with Facebook Page Insights. For example you get the total number of people who liked your Page or the total number of impressions made by people who saw content associated with your Page.

Edges

Access Tokens

  • Page access token with manage_pages and read_insights permissions

Examples

Send a GET /page-id/insights/page_impressions request:

The Request

GET graph.facebook.com/v2.11
  /page-id/insights/page_impressions
    &access_token=access-token

The Response

{
  "data": [
    {
      "name": "page_impressions",
      "period": "day",
      "values": [
        {
          "value": 2,
          "end_time": "2017-12-04T08:00:00+0000"
        },
        {
          "value": 0,
          "end_time": "2017-12-05T08:00:00+0000"
        }
      ],
      "title": "Daily Total Impressions",
      "description": "Daily: The number of impressions seen of any content associated with your Page. (Total Count)",
      "id": "page-id/insights/page_impressions/day"
    },
    {
      "name": "page_impressions",
      "period": "week",
      "values": [
        {
          "value": 38,
          "end_time": "2017-12-04T08:00:00+0000"
        },
        {
          "value": 36,
          "end_time": "2017-12-05T08:00:00+0000"
        }
      ],
      "title": "Weekly Total Impressions",
      "description": "Weekly: The number of impressions seen of any content associated with your Page. (Total Count)",
      "id": "page-id/insights/page_impressions/week"
    },
    {
      "name": "page_impressions",
      "period": "days_28",
      "values": [
        {
          "value": 79,
          "end_time": "2017-12-04T08:00:00+0000"
        },
        {
          "value": 79,
          "end_time": "2017-12-05T08:00:00+0000"
        }
      ],
      "title": "28 Days Total Impressions",
      "description": "28 Days: The number of impressions seen of any content associated with your Page. (Total Count)",
      "id": "page-id/insights/page_impressions/days_28"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/v2.11/page-id/insights?access_token=EAACEdEose0cBAMLQY1A7zF0IOkORmPwVOFLTrKDYSM96LwrW2YiSazJ9X98SzlZAmrqFqTmLZBHwZBkmmBi79iwxZCvZBSFB4EmfbQKLLxSWGWoaKvqY11QMUEe4rPnOnIxM5fsUgoCaBZCauednYP8yfbw8xSRypFPIZAqX1ZADVhgu1b2CUonjOfViQwS5Uf0LnEIA72ZBOJnsXbMPZB4ea8&pretty=0&metric=page_impressions&since=1512115200&until=1512288000",
    "next": "https://graph.facebook.com/v2.11/page-id/insights?access_token=EAACEdEose0cBAMLQY1A7zF0IOkORmPwVOFLTrKDYSM96LwrW2YiSazJ9X98SzlZAmrqFqTmLZBHwZBkmmBi79iwxZCvZBSFB4EmfbQKLLxSWGWoaKvqY11QMUEe4rPnOnIxM5fsUgoCaBZCauednYP8yfbw8xSRypFPIZAqX1ZADVhgu1b2CUonjOfViQwS5Uf0LnEIA72ZBOJnsXbMPZB4ea8&pretty=0&metric=page_impressions&since=1512460800&until=1512633600"
  }
}

Send a GET /page-id/insights/page_actions_post_reactions_like_total request:

The Request

GET graph.facebook.com/v2.11
  /page-id/insights/page_actions_post_reactions_like_total
    &access_token=access-token

The Response

{
  "data": [
    {
      "name": "page_actions_post_reactions_like_total",
      "period": "day",
      "values": [
        {
          "value": 0,
          "end_time": "2017-12-04T08:00:00+0000"
        },
        {
          "value": 0,
          "end_time": "2017-12-05T08:00:00+0000"
        }
      ],
      "title": "Daily total post like reactions of a page.",
      "description": "Daily: total post like reactions of a page.",
      "id": "page-id/insights/page_actions_post_reactions_like_total/day"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/v2.11/page-id/insights?access_token=EAACEdEose0cBAMLQY1A7zF0IOkORmPwVOFLTrKDYSM96LwrW2YiSazJ9X98SzlZAmrqFqTmLZBHwZBkmmBi79iwxZCvZBSFB4EmfbQKLLxSWGWoaKvqY11QMUEe4rPnOnIxM5fsUgoCaBZCauednYP8yfbw8xSRypFPIZAqX1ZADVhgu1b2CUonjOfViQwS5Uf0LnEIA72ZBOJnsXbMPZB4ea8&pretty=0&metric=page_actions_post_reactions_like_total&since=1512115200&until=1512288000",
    "next": "https://graph.facebook.com/v2.11/page0-id/insights?access_token=EAACEdEose0cBAMLQY1A7zF0IOkORmPwVOFLTrKDYSM96LwrW2YiSazJ9X98SzlZAmrqFqTmLZBHwZBkmmBi79iwxZCvZBSFB4EmfbQKLLxSWGWoaKvqY11QMUEe4rPnOnIxM5fsUgoCaBZCauednYP8yfbw8xSRypFPIZAqX1ZADVhgu1b2CUonjOfViQwS5Uf0LnEIA72ZBOJnsXbMPZB4ea8&pretty=0&metric=page_actions_post_reactions_like_total&since=1512460800&until=1512633600"
  }
}

Docs

Test your App

Apps can create or delete test users and use them to make API calls.

Node

Access Token

  • App access token
  • App access token for an associated app or the test user's own access token must be used to delete that test user. The test user must have been disassociated from all but a single app. You can disassociate test users using the /app-id/accounts/test-users edge.

Examples

Create a Test User

Send a POST /app-id/accounts. If name is not set a random name will be generated. Setting installed to true automatically sets the User as having the app installed. Setting permissions gives the app these permissions to the test user's data.

The Request

As of April 24,2018, the pubish_actions permission has been removed. Please see the Breaking Changes Changelog for more details. Use the App Dashboard to create test user accounts for you apps.

POST graph.facebook.com/v2.11
  /app-id/accounts
    ?name=Sirmister Pants
    &installed=true
    &permissions=publish_actions,user_posts
    &access_token=access-token

The Response

{
  "id": "user-id",
  "access_token": "access-token",
  "login_url": "https://developers.facebook.com/checkpoint/test-user-login/user-id/",
  "email": "juasgzkbhc_1512683577@tfbnw.net",
  "password": "password"
}

Delete a Test User

The Request

DELETE graph.facebook.com/v2.11
  /test-user-id
  ?access_token=access-token

The Response

{
  "success": true
}    

Post as a Test User Using your App

The Request

POST graph.facebook.com/v2.11
  /test-user-id
    ?message=Hello, I'm Mr. Pants.
    &access_token=access-token

The Response

{
  "success": true
}

Docs

Missing Something?

If you think we've missed a common scenario here, tell us using the feedback widget at the bottom of the page. Be sure to be specific about your scenario.