Using Objects

Facebook lets you post rich, structured stories from your app using a strongly typed API consisting of objects and actions. Objects are the "nouns" or targets for actions taken by people in your app.

Objects are defined by Open Graph HTML markup on web pages. If you don't have a web server to host your content, you can use the Object API to upload and publish objects.

Creating Objects

Objects are created by adding Open Graph meta tags to the page where your content is hosted. You can see a full list of object types and meta properties in our reference section. Click an object type to see all the possible properties you can add to your page to describe it.

These are the basic tags required for turning your page into an object. Add them to the <head> of your page's HTML.

<meta property="fb:app_id"          content="1234567890" /> 
<meta property="og:type"            content="article" /> 
<meta property="og:url"             content="" /> 
<meta property="og:title"           content="Introducing our New Site" /> 
<meta property="og:image"           content="" /> 
<meta property="og:description"    content="" />

In some hosting and development platforms where you create an object page and publish the object to Open Graph simultaneously, you may get an error saying that the object does not exist. This is due to a race condition that exists in some systems. We recommend that you either verify that the object page is created before you publish an action to Open Graph or introduce a small delay to account for replication lag (e.g, 15-30 seconds).


You can test your markup by passing a URL through the Sharing Debugger. This will show the tags the crawler scraped as well as any errors or warnings.

The Object Browser lets you view and edit objects for all your apps.

Reading Objects

You can read individual or multiple objects.

Individual Objects

You can retrieve the default properties of an individual object instance with the following Graph API call:

GET /{object-instance-id}

Sample Response:

  "id": "1015012577744568"
  "description": "New personal best!",
  "title": "My Run",
  "type": "fitness.course",
  "created_time": "2017-01-09T08:20:15+0000"

Multiple Objects

You can also retrieve all the objects of an object type that someone has connected to because of a specific action type via the Graph API:

GET /me/{action-type}/{object-type}

This API call must be made with an access token that has the relevant user_actions Permission. Here's an example:

GET /me/fitness.runs/fitness.course

Example Response:

  data: [ /* array of course objects that were run by a person */ ]

Getting Additional Properties

To retrieve additional object properties, include the property names using the fields parameter. For example:

GET /{object-instance-id}?fields=image

Sample Response:

  "id": "1015012577744568"
  "description": "New personal best!",
  "title": "My Run",
  "type": "fitness.course",
  "created_time": "2017-01-09T08:20:15+0000",
  "image": "”

Updating Objects

The Facebook crawler will re-scrape (and therefore update) objects:

  • When the object URL is input in the Object Debugger
  • Every 30 days after the first scrape
  • When an app triggers a scrape using an API endpoint

This Graph API endpoint is simply a call to:

POST /?id={object-instance-id or object-url}&scrape=true

The response from this endpoint will be a JSON object that contains all the information about the object that was scraped (the same data returned when the Object ID is read from the Graph API).

The id parameter can be either the canonical URL of your object or the ID of the object instance in the graph.

You can always edit an object's properties, with two exceptions:

  • Title: Once 50 actions (likes, shares and comments) have been associated with an object, you won't be able to update its title
  • Type: An object's type can't be changed once it's been used in a story

If you want to update an image for an object, we strongly suggest that the URL to the image be different than the original image URL. Caching may prevent the image from being updated.

Page Migrations and Changing URLs

If you move a page to a new URL, you can use the old URL as the canonical source for the new URL, retaining likes, comments and shares for the object. Learn how in our guide to sharing for webmasters.