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.

How to Get an Access Token

After you've implemented one of our Facebook Login SDKs, you can use its methods to get an access token with your needed permission. If the User grants your app permission, the API will respond with an access token, which you can capture using an SDK method.

Sample Code

LoginManager.getInstance().logInWithPublishPermissions(
    fragmentOrActivity,
    Arrays.asList("user_birthday"));
FBSDKLoginManager *loginManager = [[FBSDKLoginManager alloc] init];
  [loginManager logInWithPublishPermissions:@[@"user_birthday"]
                         fromViewController:self
                                    handler:^(FBSDKLoginManagerLoginResult *result, NSError
FB.login(function(response) {
  console.log(response);
}, {scope: 'user_birthday'});
If you want to confirm that the User has granted your app the 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:

Sample Response

{
  "data": [
    {
      "permission":"user_birthday",
      "status":"granted"
    }
  ]
}

To learn more about access tokens, 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

Sample Request

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}"
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/oauth/access_token",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("grant_type", "fb_exchange_token");
parameters.putString("client_id", "{your-app-id}");
parameters.putString("client_secret", "{your-app-secret}");
parameters.putString("fb_exchange_token", "{your-short-lived-access-token}");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
  initWithGraphPath:@"/oauth/access_token"
      parameters:@{ @"grant_type": @"fb_exchange_token",
                    @"client_id": @"{your-app-id}",
                    @"client_secret": @"{your-app-secret}",
                    @"fb_exchange_token": @"{your-short-lived-access-token}",}
      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/oauth/access_token',
  'GET',
  {"grant_type":"fb_exchange_token",
   "client_id":"{your-app-id}",
   "client_secret":"{your-app-secret}",
   "fb_exchange_token":"{your-short-lived-access-token}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/oauth/access_token',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Example Response

{
  "access_token": "{your-long-lived-access-token}",
  "token_type": "bearer",
  "expires_in": 5183999
}

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 a user-id, asking for Birthday and Email information using an access token with email and user_birthday permissions.

Sample Request

curl -i -X GET \
 "https://graph.facebook.com/me
   ?fields=id,name,birthday,email
   &access_token={your-user-access-token}"
GraphRequest request = GraphRequest.newMeRequest(
  accessToken,
  new GraphRequest.GraphJSONObjectCallback() {
    @Override
    public void onCompleted(JSONObject object, GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,birthday,email");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/me"
           parameters:@{ @"fields": @"id,name,birthday,email",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/me',
  'GET',
  {"fields":"id,name,birthday,email"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/me',
    array (
      'fields' => 'birthday','email',"id",'name'
    ),    
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

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.

Sample Response

{
  "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

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.

Sample Request

curl -i -X GET \
 "https://graph.facebook.com/me
   ?fields=friends
   &access_token={your-user-access-token}"
GraphRequest request = GraphRequest.newMeRequest(
  accessToken,
  new GraphRequest.GraphJSONObjectCallback() {
    @Override
    public void onCompleted(JSONObject object, GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "friends");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/me"
           parameters:@{ @"fields": @"friends",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/me',
  'GET',
  {"fields":"friends"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/me',
    array (
      'fields' => 'friends'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample 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 Facebook Pages.

To provide a way for your app Users to share content to Facebook, we encourage you to use our Sharing products instead.

Post to a Facebook Page

Endpoints

Access Token

  • Page access token with manage_pages and publish_pages permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that page.

Examples

Send a POST /id/feed request where id is a page-id to post to a Page.

Sample Request

curl -i -X POST \
 "https://graph.facebook.com/{your-page-id}/feed
   ?message=Hello%20world!
   &access_token={your-page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-page-id}/feed",
  new JSONObject("{\"message\":\"Hello world!\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/feed"
           parameters:@{ @"message": @"Hello world!",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/feed',
  'POST',
  {"message":"Hello world!"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-page-id}/feed',
    array (
      'message' => 'Hello world!'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{page-post-id}"
}

Docs

Share a Link

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

  • Page access token with manage_pages and publish_pages permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that page.

Examples

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

Sample Request

curl -i -X POST \
 "https://graph.facebook.com/{your-page-id}/feed
   ?link=https://www.facebook.com/
   &ccess_token={your-page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-page-id}/feed",
  new JSONObject("{\"link\":\"https://www.facebook.com/\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/feed"
           parameters:@{ @"link": @"https://www.facebook.com/",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/feed',
  'POST',
  {"link":"https://www.facebook.com/"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-page-id}/feed',
    array (
      'link' => 'https://www.facebook.com/'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
"id": "{page-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 /url request, where url is the link url, with the engagement field's share_count parameter.

Sample Request

curl -i -X GET \
  "https://graph.facebook.com
    ?fields=engagement{share_count} 
    &access_token={your-user-access-token}"
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/https://www.facebook.com",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "engagement{share_count}");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/https://www.facebook.com"
           parameters:@{ @"fields": @"engagement{share_count}",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/https://www.facebook.com',
  'GET',
  {"fields":"engagement{share_count}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/https://www.facebook.com',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "engagement": {
    "share_count": 752298620 
  },
  "id": "http://www.facebook.com"
}

Docs

Upload Photos and Videos

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.

  • 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

  • User access token with user_photos and publish_to_groups permissions for a user creating a group album.
  • Page access token with manage_pages and publish_pages permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that page.
  • App access token can be used for a person who has already granted user_photos and publish_to_groups permissions for creating a group album using your app.

Examples

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

Sample Request

curl -i -X POST \
  "https://graph.facebook.com/{your-group-id}/albums
    ?name=My%20New%20Album
    &access_token={your-user-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-group-id}/albums",
  new JSONObject("{\"name\":\"My New Album\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-group-id}/albums"
           parameters:@{ @"name": @"My New Album",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-group-id}/albums',
  'POST',
  {"name":"My New Album"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-group-id}/albums',
    array (
      'name' => 'My New Album'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{album-id}"
}

Docs

Post a Photo

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

  • Page access token with manage_pages and publish_pages permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that page.

Examples

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.

Sample Request

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}
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-group-id}/photos",
  new JSONObject("{\"url\":\"http://www.images.com/image.jpg\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-group-id}/photos"
           parameters:@{ @"url": @"http://www.images.com/image.jpg",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-group-id}/photos',
  'POST',
  {"url":"http://www.images.com/image.jpg"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-group-id}/photos',
    array (
      'url' => 'http://www.images.com/image.jpg'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{photo-id}"
}

The Docs

Uploading a Video

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

  • User access token with user_events and publish_videos permissions to post to an Event. The person requesting the access token must be an admin of the Event.
  • User access token with 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.
  • Page access token with manage_pages and publish_pages permissions to post to a Page. The person requesting the access token must be able to CREATE_CONTENT on that page.

Examples

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

Sample Pseudo-Code Request

POST graph-video.facebook.com/id/videos
    ?source={/path/to/file}
    &access_token={access-token}

Sample Response

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

Docs

Create Page 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

  • Page access token with manage_pages and publish_pages permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that page.

Examples

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

Sample Request

curl -i -X POST \ 
  "https://graph.facebook.com/{your-page-id}/feed
    ?message=Hello%20World!
    &published=false
    &access_token={your-page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-page-id}/feed",
  new JSONObject("{\"message\":\"Hello World!!\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/feed"
           parameters:@{ @"message": @"Hello World!!",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/feed',
  'POST',
  {"message":"Hello World!!"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-page-id}/feed',
    array (
      'message' => 'Hello World!!'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{post-id}"
}

Send a POST /id/ request where id is an unpublished post-id and the is_published field is set to true.

Sample Request

curl -i -X POST \
 "https://graph.facebook.com/{your-unpublished-page-post-id}
   ?is_published=true
   &access_token={your-page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-unpublished-page-post-id}",
  new JSONObject("{\"is_published\":\"true\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-unpublished-page-post-id}"
           parameters:@{ @"is_published": @"true",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-unpublished-page-post-id}',
  'POST',
  {"is_published":"true"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-unpublished-page-post-id}',
    array (
      'is_published' => 'true'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "success": true
}

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 permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that 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.

Sample Request

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}
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-page-id}/feed",
  new JSONObject("{\"message\":\"I love the rain!\",\"scheduled_publish_time\":\"1543389944\",\"published\":\"false\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/feed"
           parameters:@{ @"message": @"I love the rain!",@"scheduled_publish_time": @"1543389944",@"published": @"false",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/feed',
  'POST',
  {"message":"I love the rain!","scheduled_publish_time":"1543389944","published":"false"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-page-id}/feed',
    array (
      'message' => 'I love the rain!',
      'scheduled_publish_time' => '1543389944',
      'published' => 'false'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{page-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 permissions to post. The person requesting the access token must be able to CREATE_CONTENT on that 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.

Send a GET /id/feed request where id is a page-id.

Sample Request

curl -i -X GET \
  "https://graph.facebook.com/{your-page-id}/feed
    ?access_token={your-page-access-token}
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{your-page-id}/feed",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/feed"
           parameters:nil
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/feed',
  'GET',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{your-page-id}/feed',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Select the post-id you need.

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

Sample Request

curl -i -X POST \
  "https://graph.facebook.com/{your-page-post-id}
    ?backdated_time=1543303544
    &access_token={your-page-access-token}
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-page-post-id}",
  new JSONObject("{\"backdated_time\":\"1543303544\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-post-id}"
           parameters:@{ @"backdated_time": @"1543303544",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-post-id}',
  'POST',
  {"backdated_time":"1543303544"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-page-post-id}',
    array (
      'backdated_time' => '1543303544'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample 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 to view insights. The person requesting the access token must be able to ANALYZE on that page.

Examples

Send a GET /id/insights/page_actions_post_reactions_like_total request where the id is a page-id.

Sample Request

curl -i -X GET \
 "https://graph.facebook.com/{your-page-id}/insights/page_actions_post_reactions_like_total
    &access_token={your-page-access-token}"
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{your-page-id}/insights/page_actions_post_reactions_like_total",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/insights/page_actions_post_reactions_like_total"
           parameters:nil
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/insights/page_actions_post_reactions_like_total',
  'GET',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{your-page-id}/insights/page_actions_post_reactions_like_total',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample 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/{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.

Sample Request

curl -i -X GET 
  "https://graph.facebook.com/{your-page-id}/insights/page_impressions
    &access_token={your-page-access-token}
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{your-page-id}/insights/page_impressions",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/insights/page_impressions"
           parameters:nil
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/insights/page_impressions',
  'GET',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{your-page-id}/insights/page_impressions',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample 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": "{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

Test your App

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

Sample Request

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}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-app-id}/accounts",
  new JSONObject("{\"name\":\"Ted Teddy\",\"installed\":\"true\",\"permissions\":\"user_posts\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-app-id}/accounts"
           parameters:@{ @"name": @"Ted Teddy",@"installed": @"true",@"permissions": @"user_posts",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-app-id}/accounts',
  'POST',
  {"name":"Ted Teddy","installed":"true","permissions":"user_posts"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-app-id}/accounts',
    array (
      'name' => 'Ted Teddy',
      'installed' => 'true',
      'permissions' => 'user_posts'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "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}"
}

Delete a Test User

Sample Request

curl -i -X DELETE \
 "https://graph.facebook.com/{your-test-user-id}
    ?access_token={your-app-access-token}"
Bundle parameters = new Bundle();

GraphRequest request = new GraphRequest(
  accessToken,
  "/{your-test-user-id}",
  parameters,
  HttpMethod.DELETE,
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-test-user-id}"
           parameters:nil
           HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-test-user-id}',
  'DELETE',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->delete(
    '/{your-test-user-id}',
    array (),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "success": true
}    

Comment on a Page Post as a Test User Using your App

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.

Sample Request

curl -i -X POST \
 "https://graph.facebook.com/{your-test-page-post-id}/comments
   ?message=Awesome!
   &access_token={your-test-page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-test-page-post-id}/comments",
  new JSONObject("{\"message\":\"Awesome!\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-test-page-post-id}/comments"
           parameters:@{ @"message": @"Awesome!",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-test-page-post-id}/comments',
  'POST',
  {"message":"Awesome!"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-test-page-post-id}/comments',
    array (
      'message' => 'Awesome!'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

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