Skip to content
Fresh 2026

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

HTTPPHP SDKJavaScript SDKAndroid SDKiOS SDKcURL Graph API Explorer

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

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

Parameters

ParameterDescription
biz_tag_id<br>int64business tag id to filter photos
business_id<br>numeric string or integeroptional param assist with filters such as recently used
type<br>enum{profile, tagged, uploaded}Default value: profile<br>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
100Invalid parameter
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.
190Invalid OAuth 2.0 Access Token
104Incorrect signature
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 sizeFiles can not exceed 10MB. 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:

HTTPPHP SDKJavaScript SDKAndroid SDKiOS SDK

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

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

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

bash
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:

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

json
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 make a POST request to photos edge from the following paths:

  • /{page_id}/photos

When posting to this edge, a Photo will be created.

Parameters

ParameterDescription
aid<br>stringLegacy album ID. Deprecated
allow_spherical_photo<br>booleanDefault value: false<br>Indicates that we should allow this photo to be treated as a spherical photo. This will not change the behavior unless the server is able to interpret the photo as spherical, such as via Photosphere XMP metadata. Regular non-spherical photos will still be treated as regular photos even if this parameter is true.
alt_text_custom<br>stringAccessible alternative description for an image
android_key_hash<br>stringAndroid key hash
application_id<br>non-empty stringiTunes App ID. This is used by the native Share dialog that's part of iOS
attempt<br>int64Default value: 0<br>Number of attempts that have been made to upload this photo
audience_exp<br>booleanDefault value: false<br>Audience exp
backdated_time<br>datetimeA user-specified creation time for this photo
backdated_time_granularity<br>enum{year, month, day, hour, min, none}Default value: none<br>Use only the part of the backdated_time parameter to the specified granularity
caption<br>UTF-8 stringThe description of the photo<br>Supports Emoji
composer_session_id<br>stringComposer session ID
direct_share_status<br>int64The status to allow sponsor directly boost the post.
feed_targeting<br>feed targetObject that controls News Feed targeting for this post. Anyone in these groups will be more likely to see this post. People not in these groups will be less likely to see this post, but may still see it anyway. Any of the targeting fields shown here can be used, but none are required. feed_targeting applies to Pages only.
geo_locations<br>Object
countries<br>list<string>
regions<br>list<Object>
key<br>int64
cities<br>list<Object>
key<br>int64
zips<br>list<Object>
key<br>string
locales<br>list<string>Values for targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.
age_min<br>int64Must be 13 or higher. Default is 0.
age_max<br>int64Maximum age.
genders<br>list<int64>Target specific genders. 1 targets all male viewers and 2 females. Default is to target both.
college_years<br>list<int64>Array of integers. Represent graduation years from college.
education_statuses<br>list<int64>Array of integers which represent current educational status. Use 1 for high school, 2 for undergraduate, and 3 for alum (or localized equivalents).
interested_in<br>list<int64>Deprecated. Please see the Graph API Changelog for more information.<br>Deprecated
relationship_statuses<br>list<int64>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.
interests<br>list<int64>One or more IDs of pages to target fans of pages.Use type of page to get possible IDs as find Targeting Options and use the returned id to specify.
filter_type<br>int64Default value: -1<br>Unused?
full_res_is_coming_later<br>booleanDefault value: false<br>Full res is coming later
initial_view_heading_override_degrees<br>int64Manually specify the initial view heading in degrees from 0 to 360. This overrides any value present in the photo embedded metadata or provided in the spherical_metadata parameter
initial_view_pitch_override_degrees<br>int64Manually specify the initial view pitch in degrees from -90 to 90. This overrides any value present in the photo embedded metadata or provided in the spherical_metadata parameter
initial_view_vertical_fov_override_degrees<br>int64Manually specify the initial view vertical FOV in degrees from 60 to 120. This overrides any value present in the photo embedded metadata or provided in the spherical_metadata parameter
ios_bundle_id<br>stringiOS Bundle ID
is_explicit_location<br>booleanIs this an explicit location?
is_explicit_place<br>booleanIf set to true, the tag is a place, not a person
location_source_id<br>numeric string or integerID of a page or a page set that provides location informationto enable Local Extensions
manual_privacy<br>booleanDefault value: false<br>Manual privacy
message<br>stringDeprecated. Please use the caption param instead.
name<br>stringDeprecated. Please use the caption param instead.
nectar_module<br>stringNectar module. Internal apps only
no_story<br>booleanIf set to true, this will suppress the News Feed story that is automatically generated on a profile when people upload a photo using your app. Useful for adding old photos where you may not want to generate a story
offline_id<br>int64Default value: 0<br>Offline ID
og_action_type_id<br>numeric string or integerThe Open Graph action type
og_icon_id<br>numeric string or integerThe Open Graph icon
og_object_id<br>OG object ID or URL stringThe Open Graph object ID
og_phrase<br>stringThe Open Graph phrase
og_set_profile_badge<br>booleanDefault value: false<br>Flag to set if the post should create a profile badge
og_suggestion_mechanism<br>stringThe Open Graph suggestion
place<br>place tagPage ID of a place associated with the photo
privacy<br>Privacy ParameterDetermines the privacy settings of the photo. If not supplied, this defaults to the privacy level granted to the app in the Login dialog. This field cannot be used to set a more open privacy setting than the one granted
profile_id<br>intDeprecated. Use target_id instead<br>Deprecated
provenance_info<br>JSON objectprovenance_info
is_gen_ai<br>booleanis_gen_ai<br>Required
provenance_type<br>enum {C2PA, IPTC, EXPLICIT, INVISIBLE_WATERMARK, C2PA_METADATA_EDITED, IPTC_METADATA_EDITED, EXPLICIT_IMAGINE, EXPLICIT_IMAGINE_ME, EXPLICIT_RESTYLE, EXPLICIT_ANIMATE, EXPLICIT_FACE_SWAP, EXPLICIT_WARDROBE, EXPLICIT_DROP_IN}provenance_type<br>Required
source<br>stringsource
proxied_app_id<br>numeric string or integerProxied app ID
published<br>booleanDefault value: true<br>Set to false if you don't want the photo to be published immediately
qn<br>stringPhotos waterfall ID
scheduled_publish_time<br>int64Time at which an unpublished post should be published (Unix timestamp). Applies to Pages only
spherical_metadata<br>JSON objectA set of params describing an uploaded spherical photo. This field is not required; if it is not present we will try to generate spherical metadata from the metadata embedded in the image. If it is present, it takes precedence over any embedded metadata. Please click to the left to expand this list and see more information on each parameter. See also the Google Photo Sphere spec for more info on the meaning of the params: https://developers.google.com/streetview/spherical-metadata
ProjectionType<br>stringAccepted values include equirectangular (full spherical photo),<br>cylindrical (panorama), and cubestrip (also known as cubemap, e.g.<br>for synthetic or rendered content; stacked vertically with 6 faces).<br>Required
CroppedAreaImageWidthPixels<br>int64--- In equirectangular projection: As described in Google Photo Sphere<br>XMP Metadata spec.<br>--- In cylindrical projection: Very similar to equirectangular.<br>This value should be equal to the actual width of the image, and<br>together with FullPanoWidthPixels, it describes the horizontal FOV<br>of content of the image: HorizontalFOV = 360 *<br>CroppedAreaImageWidthPixels / FullPanoWidthPixels.<br>--- In cubestrip projection: This has no relationship to the pixel<br>dimensions of the image. It is simply a representation of the<br>horizontal FOV of the content of the image.<br>HorizontalFOV = CroppedAreaImageWidthPixels / PixelsPerDegree,<br>where PixelsPerDegree is defined by FullPanoWidthPixels.<br>Required
CroppedAreaImageHeightPixels<br>int64--- In equirectangular projection: As described in Google Photo Sphere<br>XMP Metadata spec.<br>--- In cylindrical projection: This value will NOT be equal to<br>the actual height of the image. Instead, together with<br>FullPanoHeightPixels, it describes the vertical FOV of the image:<br>VerticalFOV = 180 * CroppedAreaImageHeightPixels /<br>FullPanoHeightPixels. In other words, this value is equal to the<br>CroppedAreaImageHeightPixels value that this image would have, if it<br>were projected into equirectangular format while maintaining the<br>same FullPanoWidthPixels.<br>--- In cubestrip projection: This has no relationship to the pixel<br>dimensions of the image. It is simply a representation of the<br>vertical FOV of the content of the image.<br>VerticalFOV = CroppedAreaImageHeightPixels / PixelsPerDegree,<br>where PixelsPerDegree is defined by FullPanoWidthPixels.<br>Required
FullPanoWidthPixels<br>int64--- In equirectangular projection: As described in Google Photo Sphere<br>XMP Metadata spec.<br>--- In cylindrical projection: Very similar to<br>equirectangular. This value defines a ratio of horizontal pixels to<br>degrees in the space of the image, and in general the pixel to degree<br>ratio in the scope of the metadata object. Concretely, PixelsPerDegree =<br>FullPanoWidthPixels / 360. This is also equivalent to the<br>circumference of the cylinder used to model this projection.<br>--- In cubestrip projection: This value has<br>no relationship to the pixel dimensions of the image. It only defines<br>the pixel to degree ratio in the scope of the metadata object. It<br>represents the number of pixels in 360 degrees, so pixels per degree<br>is then given by: PixelsPerDegree = FullPanoWidthPixels / 360. As an<br>example, if FullPanoWidthPixels were chosen to be 3600, we would have<br>PixelsPerDegree = 3600 / 360 = 10. An image with a vertical field of<br>view of 65 degrees would then have a CroppedAreaImageHeightPixels value<br>of 65 * 10 = 650.<br>Required
FullPanoHeightPixels<br>int64--- In equirectangular projection: As described in Google Photo Sphere<br>XMP Metadata spec.<br>--- In cylindrical projection: This value is equal<br>to the FullPanoHeightPixels value that this image would have, if it<br>were projected into equirectangular format while maintaining the<br>same FullPanoWidthPixels. It is always equal to<br>FullPanoWidthPixels / 2.<br>--- In cubestrip projection: This value has<br>no relationship to the pixel dimensions of the image. It is a second,<br>redundant representation of PixelsPerDegree.<br>FullPanoHeightPixels = 180 * PixelsPerDegree. It must be consistent<br>with FullPanoWidthPixels:<br>FullPanoHeightPixels = FullPanoWidthPixels / 2.<br>Required
CroppedAreaLeftPixels<br>int64Default value: 0<br>--- In equirectangular projection: As described in Google Photo Sphere<br>XMP Metadata spec.<br>--- In cylindrical projection: This value is equal<br>to the CroppedAreaLeftPixels value that this image would have, if it<br>were projected into equirectangular format while maintaining the<br>same FullPanoWidthPixels. It is just a representation of the same<br>angular offset that it represents in equirectangular projection in the<br>Google Photo Sphere spec.<br>Concretely, AngularOffsetFromLeftDegrees = CroppedAreaLeftPixels /<br>PixelsPerDegree, where PixelsPerDegree is defined by<br>FullPanoWidthPixels.<br>--- In cubestrip projection: This value has<br>no relationship to the pixel dimensions of the image. It is just a<br>representation of the same angular offset that it represents in<br>equirectangular projection in the Google Photo Sphere spec.<br>AngularOffsetFromLeftDegrees = CroppedAreaLeftPixels / PixelsPerDegree,<br>where PixelsPerDegree is defined by FullPanoWidthPixels.
CroppedAreaTopPixels<br>int64Default value: 0<br>--- In equirectangular projection: As described in Google Photo Sphere<br>XMP Metadata spec.<br>--- In cylindrical projection: This value is equal<br>to the CroppedAreaTopPixels value that this image would have, if it<br>were projected into equirectangular format while maintaining the<br>same FullPanoWidthPixels. It is just a representation of the same<br>angular offset that it represents in equirectangular projection in the<br>Google Photo Sphere spec.<br>Concretely, AngularOffsetFromTopDegrees = CroppedAreaTopPixels /<br>PixelsPerDegree, where PixelsPerDegree is defined by<br>FullPanoWidthPixels.<br>--- In cubestrip projection: This value has<br>no relationship to the pixel dimensions of the image. It is just a<br>representation of the same angular offset that it represents in<br>equirectangular projection in the Google Photo Sphere spec.<br>AngularOffsetFromTopDegrees = CroppedAreaTopPixels / PixelsPerDegree,<br>where PixelsPerDegree is defined by FullPanoWidthPixels.
PoseHeadingDegrees<br>float
PosePitchDegrees<br>float
PoseRollDegrees<br>float
InitialViewHeadingDegrees<br>float
InitialViewPitchDegrees<br>float
InitialViewRollDegrees<br>floatThis is not currently supported
InitialViewVerticalFOVDegrees<br>floatThis is deprecated. Please use InitialVerticalFOVDegrees.
InitialVerticalFOVDegrees<br>floatYou can set the intial vertical FOV of the image. You can set either<br>this field or InitialHorizontalFOVDegrees.
InitialHorizontalFOVDegrees<br>floatYou can set the intial horizontal FOV of the image. You can set either<br>this field or InitialVerticalFOVDegrees.
PreProcessCropLeftPixels<br>int64
PreProcessCropRightPixels<br>int64
sponsor_id<br>numeric string or integerFacebook Page id that is tagged as sponsor in the photo post
sponsor_relationship<br>int64Sponsor Relationship, such as Presented By or Paid PartnershipWith
tags<br>list<Object>Default value: Vec<br>Tags on this photo
x<br>floatThe x-axis offset for the tag
y<br>floatThe y-axis offset for the tag
tag_uid<br>intThe user_id of the tagged person
tag_text<br>stringText associated with the tag
target_id<br>intDon't use this. Specifying a target_id allows you to post the photo to an object that's not the user in the access token. It only works when posting directly to the /photos endpoint. Instead of using this parameter you should be using the edge on an object directly, like /page/photos.
targeting<br>targetAllows you to target posts to specific audiences. Applies to Pages only
geo_locations<br>Object
countries<br>list<string>
regions<br>list<Object>
key<br>int64
cities<br>list<Object>
key<br>int64
zips<br>list<Object>
key<br>string
locales<br>list<string>
excluded_countries<br>list<string>
excluded_regions<br>list<int64>
excluded_cities<br>list<int64>
excluded_zipcodes<br>list<string>
timezones<br>list<int64>
age_min<br>enum {13, 15, 18, 21, 25}
temporary<br>booleanDefault value: false<br>This is a temporary photo. published must be false, and you can't set scheduled_publish_time
time_since_original_post<br>int64Same as backdated_time but with a time delta instead of absolute time
uid<br>intDeprecated
unpublished_content_type<br>enum {SCHEDULED, SCHEDULED_RECURRING, DRAFT, PUBLISH_PENDING, ADS_POST, INLINE_CREATED, PUBLISHED, REVIEWABLE_BRANDED_CONTENT}Content type of the unpublished content type
url<br>URLThe URL of a photo that is already uploaded to the Internet. You must specify this or a file attachment
user_selected_tags<br>booleanDefault value: false<br>User selected tags
vault_image_id<br>numeric string or integerA vault image ID to use for a photo. You can use only one of url, a file attachment, vault_image_id, or sync_object_uuid

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

post_id: string,

}

Error Codes

ErrorDescription
368The action attempted has been deemed abusive or is otherwise disallowed
324Missing or invalid image file
200Permissions error
190Invalid OAuth 2.0 Access Token
100Invalid parameter
240Desktop applications cannot call this function for other users
283That action requires the extended permission pages_read_engagement and/or pages_read_user_content and/or pages_manage_ads and/or pages_manage_metadata

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.