Graph API Version

Page Photos

Profile pictures and uploaded pictures for a Facebook Page.

Reading

Retrieve the photos associated to a page.

New Page Experience

This endpoint is supported for New Page Experience.

Feature Permissions

NameDescription
Page Public Content AccessThis feature permission may be required.
When using the Page Public Content Access feature, use a system user access token to avoid rate limiting issues.

Requirements

You will need:
  • A Page access token requested by a person who can perform the MODERATE task on the Page
  • The pages_read_engagement permission
  • The pages_show_list permission
If a person is not able to perform the task on the Page, you will need:
  • The Pages Public Content Access feature

Example

Graph API Explorer
GET /v19.0/{page-id}/photos HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{page-id}/photos',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/photos",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/photos",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/photos"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/{page-id}/photos
If you want to learn how to use the Graph API, read our Using Graph API guide.

By default reading from the photos edge returns the current profile picture for the Page as well as previous profile pictures. Use the optional type parameter with the value uploaded to get the photos that a Page has uploaded.

GET /{page-id}/photos?type=uploaded

Parameters

ParameterDescription
biz_tag_id
int64

business tag id to filter photos

business_id
numeric string or integer

optional param assist with filters such as recently used

type
enum{profile, tagged, uploaded}
Default value: profile

Allows you to query which type of photos to return

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of Photo nodes.

paging

For more details about pagination, see the Graph API guide.

Error Codes

ErrorDescription
200Permissions error
80001There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
100Invalid parameter
190Invalid OAuth 2.0 Access Token
368The action attempted has been deemed abusive or is otherwise disallowed

Creating

Requirements

  • A Page access token requested by a person who can perform the CREATE_CONTENT task on the Page
  • The pages_read_engagement permission
  • The pages_manage_posts permission
  • The pages_show_list permission

Photo Specifications

PropertySpecification

File type

.jpeg, .bmp, .png, .gif, .tiff

File size

Files can not exceed 4MB. For .png files, we recommend not exceeding 1MB or the image may appear pixelated.

Facebook strips all location metadata before publishing and resizes images to different dimensions to best support rendering in multiple sizes.

Uploading Photos

There are two separate ways of uploading photos to Facebook:

  • Attach the photo as multipart/form-data. The name of the object doesn't matter, but historically people have used source as the parameter name for the photo. How this works depends on the SDK you happen to be using to do the post.

  • Use a photo that is already on the internet by publishing using the url parameter:

POST /v19.0/page-id/photos HTTP/1.1
Host: graph.facebook.com

url=image-url
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/page-id/photos',
    array (
      'url' => 'image-url',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/page-id/photos",
    "POST",
    {
        "url": "image-url"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("url", "image-url");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/page-id/photos",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"url": @"image-url",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/page-id/photos"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Single Photo Page Post

You can upload and publish a single photo in one API request.

curl -i -X POST \
 -d "url=https://www.facebook.com/images/fb_icon_325x325.png" \
 -d "published=true" \
 -d "access_token=<access_token>" \
 "https://graph.facebook.com/me/photos"

Uploading an unpublished photo

Upload a photo without publishing it to the /{page-id}/photos edge by making a similar call as described in the single photo post section but by adding the argument published=false.

curl -i -X POST \
 -d "url=https://www.facebook.com/images/fb_icon_325x325.png" \
 -d "published=false" \
 -d "access_token=<access_token>" \
 "https://graph.facebook.com/me/photos"

If the photo is used in a scheduled post, temporary=true must be used.

curl -i -X POST \
 -d "url=https://www.facebook.com/images/fb_icon_325x325.png" \
 -d "published=false" \
 -d "temporary=true" \
 -d "access_token=<access_token>" \
 "https://graph.facebook.com/me/photos"

Use the Graph API Explorer to get SDK code snippets of the requests.

On successful upload, the Graph API provides a response including the photo ID. After you upload an unpublished photo, Facebook stores it in a temporary upload state, which means it will remain on Facebook servers for about 24 hours. If you do not publish these photos within 24 hours, we delete them.

Publishing a multi-photo post with uploaded photos

After you successfully upload all photos, you can publish a multi-photo post using the returned ids by using the /page-id/feed endpoint. Here is an example of a request:

curl -i -X POST \
 -d "message=Testing multi-photo post!" \
 -d "attached_media[0]={"media_fbid":"1002088839996"}" \
 -d "attached_media[1]={"media_fbid":"1002088840149"}" \
 -d "access_token=<access_token>" \
 "https://graph.facebook.com/me/feed"

When the photos are part of a scheduled post, the published, scheduled_publish_time, and unpublished_content_type parameters must be included.

curl -i -X POST \
 -d "message=Testing multi-photo post!" \
 -d "attached_media[0]={"media_fbid":"1002088839996"}" \
 -d "attached_media[1]={"media_fbid":"1002088840149"}" \
 -d "access_token=<access_token>" \
 -d "published=false" \
 -d "scheduled_publish_time=1512068400" \
 -d "unpublished_content_type=SCHEDULED" \
 "https://graph.facebook.com/me/feed"

Use the Graph API Explorer to get SDK code snippets of the requests.

When publishing to a page using the Graph API Explorer the media_fbids must appear as an array in one Value box, [{"media_fbid":"photo_id"},{"media_fbid":"photo_id"}] or an error will occur.

A successful Graph API request returns the Page Post ID.

If you receive any errors, it's typically because of a permission failure or a bad parameter.

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.