Graph API

Overview
The Graph API is the primary way to get data into and out of the Facebook platform. It's an HTTP-based API that apps can use to programmatically query data, post new stories, manage ads, upload photos, and perform a wide variety of other tasks.
The Graph API is named after the idea of a "social graph" — a representation of the information on Facebook. It's composed of nodes, edges, and fields. Typically you use nodes to get data about a specific object, use edges to get collections of objects on a single object, and use fields to get data about a single object or each object in a collection. Throughout our documentation, we may refer to both a node and edge as an "endpoint". For example, "send a GET request to the User endpoint".
HTTP
All data transfers conform to HTTP/1.1, and all endpoints require HTTPS. Because the Graph API is HTTP-based, it works with any language that has an HTTP library, such as cURL and urllib. This means you can use the Graph API directly in your browser. For example, requesting this URL in your browser...
​https://graph.facebook.com/facebook/picture?redirect=false​
... is equivalent to performing this cURL request:
1
curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"
Copied!
We have also enabled the includeSubdomains HSTS directive on facebook.com, but this should not adversely affect your Graph API calls.
Host URL
Almost all requests are passed to the graph.facebook.com host URL. The single exception is video uploads, which use graph-video.facebook.com.
Access Tokens
Access tokens allow your app to access the Graph API. Almost all Graph API endpoints require an access token of some kind, so each time you access an endpoint, your request may require one. They typically perform two functions:
They allow your app to access a User's information without requiring the User's password. For example, your app needs a User's email to perform a function. If the User agrees to allow your app to retrieve their email address from Facebook, the User will not need to enter their Facebook password for your app to get their email address.
They allow us to identify your app, the User who is using your app, and the type of data the User has permitted your app to access.
Visit our access token documentation to learn more.
Nodes
A node is an individual object with a unique ID. For example, there are many User node objects, each with a unique ID representing a person on Facebook. Pages, Groups, Posts, Photos, and Comments are just some of the nodes of the Facebook Social Graph.
The following cURL example represents a call to the User node.
1
curl -i -X GET \
2
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"
Copied!
This request would return the following data by default, formatted using JSON:
1
{
2
  "name": "Your Name",
3
  "id": "YOUR-USER-ID"
4
}
Copied!
Node Metadata
You can get a list of all fields, including the field name, description, and data type, of a node object, such as a User, Page, or Photo. Send a GET request to an object ID and include the metadata=1 parameter:
1
curl -i -X GET \
2
  "https://graph.facebook.com/USER-ID?
3
    metadata=1&access_token=ACCESS-TOKEN"
Copied!
The resulting JSON response will include the metadata property that lists all the supported fields for the given node:
1
{
2
  "name": "Jane Smith",
3
  "metadata": {
4
    "fields": [
5
      {
6
        "name": "id",
7
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
8
        "type": "numeric string"
9
      },
10
      {
11
        "name": "age_range",
12
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
13
        "type": "agerange"
14
      },
15
      {
16
        "name": "birthday",
17
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
18
        "type": "string"
19
      },
20
...
Copied!
/me
The /me node is a special endpoint that translates to the object ID of the person or Page whose access token is currently being used to make the API calls. If you had a User access token, you could retrieve a User's name and ID by using:
1
curl -i -X GET \
2
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"
Copied!
Edges
An edge is a connection between two nodes. For example, a User node can have photos connected to it, and a Photo node can have comments connected to it. The following cURL example will return a list of photos a person has published to Facebook.
1
curl -i -X GET \
2
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"
Copied!
Each ID returned represents a Photo node and when it was uploaded to Facebook.
1
    {
2
  "data": [
3
    {
4
      "created_time": "2017-06-06T18:04:10+0000",
5
      "id": "1353272134728652"
6
    },
7
    {
8
      "created_time": "2017-06-06T18:01:13+0000",
9
      "id": "1353269908062208"
10
    }
11
  ],
12
}
Copied!
Fields
Fields are node properties. When you query a node, or an edge, it returns a set of fields by default, as the examples above show. However, you can specify which fields you want returned by using the fields parameter and listing each field. This overrides the defaults and returns only the fields you specify, and the ID of the object, which is always returned.
The following cURL request includes the fields parameter and the User's name, email, and profile picture.
1
curl -i -X GET \
2
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"
Copied!
Data Returned
1
{
2
  "id": "USER-ID",
3
  "name": "EXAMPLE NAME",
4
  "email": "[email protected]",
5
  "picture": {
6
    "data": {
7
      "height": 50,
8
      "is_silhouette": false,
9
      "url": "URL-FOR-USER-PROFILE-PICTURE",
10
      "width": 50
11
    }
12
  }
13
}
Copied!
Complex Parameters
Most parameter types are straightforward primitives such as bool, string and int, but there are also list and object types that can be specified in the request.
The list type is specified in JSON syntax, for example: ["firstitem", "seconditem", "thirditem"]
The object type is also specified in JSON syntax, for example: {"firstkey": "firstvalue", "secondKey": 123}
Publishing, Updating, and Deleting
Visit our Facebook Sharing guide to learn how to publish to a User's Facebook or our Pages API documentation to publish to a Page's Facebook feed.
Some nodes allow you to update fields with POST operations. For example, you could update your email field like this:
1
curl -i -X POST \
2
  "https://graph.facebook.com/[email protected]&access_token=ACCESS-TOKEN"
Copied!
Read-After-Write
For create and update endpoints, the Graph API can immediately read a successfully published or updated object and return any fields supported by the corresponding read endpoint.
By default, an ID of the object created or updated will be returned. To include more information in the response, include the fields parameter in your request and list the fields you want returned. For example, to publish the message “Hello” to a Page's feed, you could make the following request:
1
curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
2
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
Copied!
The above code example is formatted for readability.
This would return the specified fields as a JSON-formatted response, like this:
1
{
2
  "created_time": "2017-04-06T22:04:21+0000",
3
  "from": {
4
    "name": "My Facebook Page",
5
    "id": "PAGE-ID"
6
  },
7
  "id": "POST_ID",
8
  "message": "Hello",
9
}
Copied!
Refer to each endpoint's reference documentation to see if it supports read-after-write and what fields are available.
Errors
If the read fails for any reason (for example, requesting a non-existent field), the Graph API will respond with a standard error response. Visit our Handling Errors guide for more information.
You can usually delete a node, such as a Post or Photo node, by performing a DELETE operation on the object ID:
1
curl -i -X DELETE \
2
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"
Copied!
Usually you can only delete nodes that you created, but check each node's reference guide to see requirements for delete operations.
Versions
The Graph API has multiple versions with quarterly releases. You can specify the version in your calls by adding "v" and the version number to the start of the request path. For example, here's a call to version 4.0:
1
curl -i -X GET \
2
  "https://graph.facebook.com/v4.0/USER-ID/photos
3
    ?access_token=ACCESS-TOKEN"
Copied!
If you do not include a version number we will default to the oldest available version, so it's recommended to include the version number in your requests.
You can read more about versions in our Versioning guide and learn about all available versions in the Graph API Changelog.
Facebook APIs, SDKs, and Platforms
Connect interfaces and develop across platforms using Facebook's various APIs, SDKs, and platforms.
Next Steps
​Get Started with Graph API – Let's explore the Facebook Social Graph using the Graph Explorer tool and run a couple requests to get data.
Guides
Various Guides for how to use the Facebook Graph API to send and receive data to the Facebook Social Graph.
Batch Requests
The Batch Requests guide describes how to make multiple Graph API requests in one call.
Debugging
The Debug Requests guide describes how to enable Debug Mode to view Graph API responses that may contain additional fields that explain potential issues with an API call.
Error Handling
The Handling Errors guide describes the recovery tactics and provides a list of error values with a map to the most common recovery tactic to use.
Graph Explorer Guide
The Graph API Explorer guide describes how to use the Graph Explorer tool](/tools/explorer). This tool allows you to construct, test, and debug queries and see their responses for any apps on which you have an admin, developer, or tester role.
Upload Files
The Upload Files guide describes how to upload photos and videos to the Facebook Social Graph that can then be shared in User, Group, or Page posts.
Graph API Reference
Graph API Root Nodes
This is a full list of the Graph API root nodes. The main difference between a root node and a non-root node is that root nodes can be queried directly, while non-root nodes can be queried via root nodes or edges. If you want to learn how to use the Graph API, read our Using Graph API guide, and if you want to know which APIs can solve some frequent issues, try our Common Scenarios guide.
Node
Description
​Album​
Get Fields and Edges on an Album.
​App Request​
An individual app request received by someone, sent by an app or another person
​Application​
A Facebook app
​Async Session​
Represents an async job request to Graph API
​Atlas Ad Set​
An Atlas AdSet
​Atlas Campaign​
An Atlas Campaign
​Atlas FBConversion Event​
Conversion Event Node
​Atlas Publisher​
An Atlas Publisher
​Atlas Report​
An Atlas Report
​Atlas Report Run​
An Atlas ReportRun
​Atlas Report Schedule​
An Atlas ReportSchedule
​Atlas Tracking Connection​
An Ad Platform Tracking Connection
​Business Unit​
Represents a group of certain types of Business objects in a Business. Will be used by Measurement Hub initially with more usage coming later on.
​CPASAdvertiser Partnership Recommendation​
Returns a recommendation of a single retailer for a specific brand. This endpoint returns a retailer-brand pair and an advertiser who can advertise on behalf of the producer.
This endpoint is mainly for Facebook’s Marketing Partners using Collaborative Ads.
​CPASCollaboration Request​
A collaboration request is a partnership request coming from a brand or agency to a retailer or marketing partner. Used for Collaborative Ads.
​CTCert Domain​
A domain name that has been issued new certificates.
​Canvas​
A canvas document
​Canvas Button​
A button inside the canvas
​Canvas Carousel​
A carousel inside a canvas
​Canvas Footer​
A footer of the canvas
​Canvas Header​
A header inside the canvas.
​Canvas Photo​
A photo inside a canvas
​Canvas Product List​
A product list inside the canvas
​Canvas Product Set​
A product set inside the canvas
​Canvas Store Locator​
A store locator inside the canvas
​Canvas Text​
Text element of the canvas
​Canvas Video​
A video inside canvas
​Collaborative Ads Directory​
Directory of retailers that use Collaborative Ads. This endpoint must be used in conjunction with the collaborative_ads_merchants field below.
​Comment​
A comment can be made on various types of content on Facebook. Most Graph API nodes have a /comments edge that lists all the comments on that object. The /comment node returns a single comment.
​Commerce Merchant Settings​
Commerce Merchant Settings object
​Commerce Order​
Represents an order placed directly on Facebook or Instagram
​Conversation​
Graph API Reference Conversation /conversation
​Destination​
Represents a destination in a catalog
​Doc​
A Document
​Event​
Get fields and edges on an Event.
​Flight​
Represents a flight in a catalog
​Friend List​
This represents a user's friend list on Facebook
​Group​
A Facebook group.
​Group Doc​
Graph API Reference Group Doc /group-doc
​Group Message​
GroupMessage
​Image Copyright​
Represents a copyright on an image asset.
​Instagram Oembed​
InstagramOembed
​Lead Gen Data​
A lead ad form
​Link​
A link shared on a wall.
​Live Encoder​
Get fields and edges on a LiveEncoder.
​Live Video​
Get fields and edges on a LiveVideo.
​Live Video Input Stream​
An ingest stream for a live video
​Mailing Address​
A mailing address object
​Media Fingerprint​
Media fingerprint
​Message​
An individual message in the Facebook messaging system.
​Milestone​
Graph API Reference Milestone /milestone
​Native Offer​
A native offer represents an Offer on Facebook. The /{offer_id} node returns a single native offer. Each native offer requires a view to be rendered to users.
​Object Comments​
This reference describes the /comments edge that is common to multiple Graph API nodes. The structure and operations are the same for each node.
​Object Likes​
This reference describes the /likes edge that is common to multiple Graph API nodes. The structure and operations are the same for each node.
​Object Private Replies​
Private replies for an object
​Object Reactions​
First revision to publish
​Object Sharedposts​
Graph API Reference /object/sharedposts
​Oembed Page​
OembedPage
​Oembed Post​
OembedPost
​Oembed Video​
OembedVideo
​Offline Conversion Data Set​
A Data Set for Offline Conversions object
​Offline Conversion Data Set Upload​
A subset of Offline Event Data Set
​Page​
Get groups a Page is a member of.
​Page Call To Action​
Page's call-to-action
​Page Post​
A Facebook feed story
​Page Upcoming Change​
Notification of page upcoming changes.
​Page/insights​
This object represents a single Insights metric that is tied to another particular Graph API object (Page, App, Post, etc.).
​Payment​
Graph API Reference Payment /payment
​Photo​
This represents a Photo on Facebook.
​Place​
A place
​Place Topic​
The category of a place Page
​Post​
A Facebook Feed story
​Profile​
Graph API Reference Profile /profile
​RTBDynamic Post​
A dynamically generated Post, used for Dynamic Ad Creatives
​Request​
Graph API Reference Request /request
​Store Catalog Settings​
Represents settings specific to local inventory of a product catalog
​Test User​
Graph API Reference Test User /test-user
​Thread​
Graph API Reference Thread /thread
​User​
Get fields and edges on a User.
​Video​
A Video
​Video Copyright​
A video copyright
​Video Copyright Rule​
A video copyright rules
​Video List​
A playlist for videos
​Video Poll​
Embedded video poll
​Video Poll Option​
Represents a single poll option that may be selected by the user
​Whats App Business Account​
Returns the account information of a WhatsApp Business Account
​Whats App Business Account To Number Current Status​
Returns information about a specific phone number.
​Whats App Business HSM​
Retrieves information about the message template
Graph API Root Edges
Root edges are edges that can be queried directly. They allow you to access collections of nodes that are not on a parent node.
Node
Description
​Ads Archive​
Returns archived ads based on your search. By default we only return all ads that are eligible for delivery and that have the ACTIVE status.
​Debug Token​
DebugToken
Pandoc
Troubleshooting
Last modified 14d ago
Copy link
Contents
Publishing, Updating, and Deleting
Versions
Facebook APIs, SDKs, and Platforms
Next Steps
Guides
Graph API Reference