The Graph API for scores allows game developers to publish user scores compared with their friends to provides more meaningful and relevant stories.

Note that this API is only available to applications categorized as 'Games'. You can categorize your app as 'Games' in the Developer app by navigating to About > Basic Info and selecting 'Games` in the drop down menu in the category field.

Managing Scores for a user

The user object as well as the app object have scores connection which allows you to manage scores for your app.

Read scores for a user

You can read the scores for a user for your app by issuing an HTTP GET request to /USER_ID/scores with user or app access_token for that app.

• If the user has granted your app with the user_games_activity permission then this api will give you latest scores for all apps for that user. Otherwise it will give you scores only for your app.
• The friends_games_activity permission will enable you to access scores for users' friends for all apps by issuing an HTTP GET request to /FRIEND_ID/scores.

The API returns an array of objects containing the following data:

Name	Description	Type
user	User associated with the scores.	object containing the name and id for the user.
score	Numeric score.	integer
application	App associated with the score.	object containing the name and id of the app.
type	type of the data which is "score".	string

Read scores for a user and their friends

You can read the scores for the user and their friends for your app by issuing an HTTP GET request to /APP_ID/scores with the user access_token for that app. This returns the list of latest scores for the user and their friends who have authorized the app. You can use this api to create leaderboard for the user and their friends.

The API returns an array of objects containing the following data:

Name	Description	Type
user	User associated with the scores.	object containing the name and id for the user.
score	Numeric score.	integer
application	App associated with the score.	object containing the name and id of the app.
type	type of the data which is "score".	string

Create or update a score for a user

You can post a score or a user by issuing an HTTP POST request to /USER_ID/scores with the app access_token as long as you have the publish_actions permission.

Name	Description	Type	Required
score	numeric score with value > 0.	integer	yes

Return value

Description	Type
Whether the write succeeded.	boolean

Delete scores for a user

You can delete the score for a user for your app by issuing an HTTP DELETE request to /USER_ID/scores with the app access_token as long as your app has the publish_actions permission.

Response

Description	Type
true or error depending on whether the delete was successful.	boolean

Delete all scores for the app

You can delete all the scores for your app by issuing an HTTP DELETE request to /APP_ID/scores with the app access_token for that app. This will reset the scores for your app. Use this if you'd like to periodically reset your game's scores and leaderboards.

Response

Description	Type
true or error depending on whether the delete was successful.	boolean

Next steps

• Showing Scores aggregation previews in the Auth Dialog