The Graph API is a powerful resource which can be used in various 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.
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.
LoginManager.getInstance().logInWithPublishPermissions(
fragmentOrActivity,
Arrays.asList("user_birthday"));
user_birthday
permission, you can perform a GET
operation on the /{user-id}/permissions
edge. Assuming the User granted the permission, the API response would look like this:
{ "data": [ { "permission":"user_birthday", "status":"granted" } ] }
To learn more about access tokens, please visit our Access Token Guide.
In some instances, you may need a long-lived access token. Convert a short-lived token to a long-lived one.
Examples
curl -i -X GET \
"https://graph.facebook.com/oauth/access_token
?grant_type=fb_exchange_token
&client_id={your-app-id}
&client_secret={your-app-secret}
&fb_exchange_token={your-short-lived-access-token}
&access_token={your-short-lived-access-token}"
{ "access_token": "{your-long-lived-access-token}", "token_type": "bearer", "expires_in": 5183999 }
Docs
Getting information about you or other Facebook Users is an identical process; all that is needed is a User's Facebook ID.
Node
Permissions
Permissions depend on the type of data you are requesting. Default permissions for public profile information include name and profile picture. For all other data, you need specific permissions for that data. You must request permission from the User to access private information.
Examples
Send a GET /id
request, where id
is either a user-id, asking for Birthday and Email information using an access token with email
and user_birthday
permissions.
curl -i -X GET \
"https://graph.facebook.com/me
?fields=id,name,birthday,email
&access_token={your-user-access-token}"
The /me
node is a special endpoint that translates to the user_id
of the person (or the page_id
of the Facebook Page) whose access token is currently being used to make the API calls. If you run the above example using an access token you requested, /me
would be your user-id.
{ "id": "{user-id}", "name": "Fiona Fox", "birthday": "01/01/1985", "email": "fiona@example.com" }
If information is missing from the response the User may not have filled out those fields or a permission is missing.
Docs
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_friends
permissionsExamples
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.
curl -i -X GET \
"https://graph.facebook.com/me
?fields=friends
&access_token={your-user-access-token}"
{ "data": [ { "name": "Julia Goulia", "id": "julia's-user-id" }, { "name": "Steven Even", "id": "steven's-user-id" } ], "summary": { "total_count": 156 } }
Docs
Apps can create new status updates on behalf of Facebook Pages.
To provide a way for your app Users to share content to Facebook, we encourage you to use our Sharing products instead.
Endpoints
Access Token
CREATE
task on the PageExamples
Send a POST /id/feed
request where id
is a page-id to post to a Page.
curl -i -X POST \
"https://graph.facebook.com/{your-page-id}/feed
?message=Hello%20world!
&access_token={your-page-access-token}"
{ "id": "{page-post-id}" }
Docs
Apps can share links to content on other websites on behalf of Facebook Pages. To provide a way for your app Users to share content to their Timeline, we encourage you to use our Sharing products.
The Edges
Access Tokens
CREATE
task on the PageExamples
POST /id/feed
request where id
is page-id and add the link
field with value of a url. curl -i -X POST \
"https://graph.facebook.com/{your-page-id}/feed
?link=https://www.facebook.com/
&ccess_token={your-page-access-token}"
{ "id": "{page-post-id}" }
Docs
Find how many times a url has been shared on Facebook.
Nodes
Access Token
read_stream
permission for any other links.Examples
Send a GET /url
request, where url
is the link url, with the engagement
field's share_count
parameter.
curl -i -X GET \
"https://graph.facebook.com
?fields=engagement{share_count}
&access_token={your-user-access-token}"
{ "engagement": { "share_count": 752298620 }, "id": "http://www.facebook.com" }
Docs
Apps are able to create and publish new photo Albums, and publish photos or videos via the Graph API on behalf of Facebook Groups or Pages. To provide a way for your app Users to share content to their Facebook Timeline, we encourage you to use our Sharing products instead.
The Edges
Access Token
For a Group:
user_photos
and publish_to_groups
permissions for a user creating a group album.user_photos
and publish_to_groups
permissions for creating a group album using your app.For a Page:
CREATE
task on the PageExamples
Create a POST /id/albums
request where id
is the page-id or group-id and set name
to the name of your Album.
curl -i -X POST \
"https://graph.facebook.com/{your-group-id}/albums
?name=My%20New%20Album
&access_token={your-user-access-token}"
{ "id": "{album-id}" }
Docs
Apps are able to publish photos to Albums via the Graph API on behalf of Facebook Groups or Pages. To provide a way for your app Users to share content to their Facebook Timeline, we encourage you to use our Sharing products instead.
The Edges
Access Token
CREATE
task on the PageExamples
Create a POST /id/photos
request where id
can be a page-id or group-id and set url
to the url of your photo or source
to the source of your image.
curl -i -X POST \
"https://graph.facebook.com/{your-group-id}/photos
?url=http://www.images.com/image.jpg
&access_token={your-user-access-token}
{ "id": "{photo-id}" }
The Docs
Apps are able to upload videos to the Graph API to post on behalf of Facebook Events, Groups, or Pages. Videos must be published to the graph-video.facebook.com
instead of the usual Graph API url, graph.facebook.com. To provide a way for your app Users to share content to their Facebook Timeline, we encourage you to use our Sharing products instead.
The Edges
Access Tokens
For a Group:
user_events
and publish_videos
permissions to post to an Event. The person requesting the access token must be an admin of the Event.publish_to_groups
and publish_videos
permissions to post to an Group. The person requesting the access token must be an admin of the Group.For a Page:
CREATE
task on the PageExamples
Create a POST /id/videos
request where id
can be an event-id, group-id or page-id.
POST graph-video.facebook.com/id/videos ?source={/path/to/file} &access_token={access-token}
{ "id": "{video-id}" "post_id": "{post-id}" }
Docs
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
CREATE
task on the PageExamples
Send a POST /id/feed
request where id
is a page-id and the published
field is set to false
.
curl -i -X POST \
"https://graph.facebook.com/{your-page-id}/feed
?message=Hello%20World!
&published=false
&access_token={your-page-access-token}"
{ "id": "{post-id}" }
Send a POST /id/
request where id
is an unpublished post-id and the is_published
field is set to true
.
curl -i -X POST \
"https://graph.facebook.com/{your-unpublished-page-post-id}
?is_published=true
&access_token={your-page-access-token}"
{ "success": true }
Docs
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 75 days from the time of publish. You can update this scheduled time by updating the post with a new scheduled_publish_time
.
Edges
Access Tokens
CREATE
task on the PageExamples
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.
curl -i -X POST \
"https://graph.facebook.com/{your-page-id}/feed
?message=I%20love%20the%20rain!
&published=false
&scheduled_publish_time=1543389944
&access_token={your-page-access-token}
{ "id": "{page-post-id}" }
Docs
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
CREATE
task on the PageExamples
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.
Send a GET /id/feed
request where id
is a page-id.
curl -i -X GET \
"https://graph.facebook.com/{your-page-id}/feed
?access_token={your-page-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.
curl -i -X POST \
"https://graph.facebook.com/{your-page-post-id}
?backdated_time=1543303544
&access_token={your-page-access-token}
{ "success": true }
Docs
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
CREATE
task on the Pageread_insights
permissionExamples
Send a GET /id/insights/page_actions_post_reactions_like_total
request where the id
is a page-id.
curl -i -X GET \
"https://graph.facebook.com/{your-page-id}/insights/page_actions_post_reactions_like_total
&access_token={your-page-access-token}"
{ "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/{your-page-id}/insights?access_token={your-page-access-token}", "next": "https://graph.facebook.com/{your-page-id}/insights?access_token={your-page-access-token}" } }
Send a GET /id/insights/page_impressions
request where id
is a page-id.
curl -i -X GET
"https://graph.facebook.com/{your-page-id}/insights/page_impressions
&access_token={your-page-access-token}
{ "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": "{your-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": "{your-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": "{your-page-id}/insights/page_impressions/days_28" } ], "paging": { "previous": "https://graph.facebook.com/{your-page-id}/insights?access_token={your-page-access-token}", "next": "https://graph.facebook.com/{your-page-id}/insights?access_token={your-page-access-token}" } }
Docs
Apps can create or delete test users and comment on a post as a test user. You can also use the App Dashboard to create test user accounts for you apps.
Node
Access Token
/app-id/accounts/test-users
edge.Examples
Send a POST /id/accounts
where id
is an app-id and set name
, installed
to true
, which automatically sets the User as having the app installed, and permissions
, which gives the app these permissions to the Test User's data. If name
is not set a random name will be generated.
curl -i -X POST \
"https://graph.facebook.com/{your-app-id}/accounts
?name=Ted Teddy
&installed=true
&permissions=user_posts
&access_token={your-app-access-token}"
{ "id": "{your-test-user-id}", "access_token": "{your-test-user-access-token}", "login_url": "https://developers.facebook.com/checkpoint/test-user-login/{your-test-user-id}/", "email": "{your-test-user-email}", "password": "{your-test-user-password}" }
curl -i -X DELETE \
"https://graph.facebook.com/{your-test-user-id}
?access_token={your-app-access-token}"
{ "success": true }
A Test User can only comment on a Page Post where the Test User is able to CREATE_CONTENT
on that page, like a Page created by that Test User.
curl -i -X POST \
"https://graph.facebook.com/{your-test-page-post-id}/comments
?message=Awesome!
&access_token={your-test-page-access-token}"
{ "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.