GET (/users/xuid({xuid})/scids/{scid}/stats?include=valuemetadata)

Article
06/22/2023

Gets a list of specified statistics, including metadata associated with the statistic values, for a user in a specified service configuration. The domain for these URIs is userstats.xboxlive.com.

Remarks
URI parameters
Query string parameters
Authorization
Required Request Headers
Optional Request Headers
Request body
HTTP status codes
Response body

Remarks

The ?include=valuemetadata query parameter allows the response to include any metadata associated with the user stat values, such as the model and color of a car used to achieve a time on a race track.

To include value metadata in the response, the request call must also set the header value X-Xbl-Contract-Version to 3.

URI parameters

Parameter	Type	Description
xuid	GUID	Xbox User ID (XUID) of the user on whose behalf to access the service configuration.
scid	GUID	Identifier of the service configuration that contains the resource being accessed.

Query string parameters

Parameter	Type	Description
statNames	string	A comma delimited list of user statistic names.For example, the following URI informs the service that four statistics are requested on behalf of the user id specified in the URI.{::nomakrdown} `https://userstats.xboxlive.com/users/xuid({xuid})/scids/{scid}/stats/wins,kills,kdratio,headshots?include=valuemetadata`
include=valuemetadata	string	Indicates that the response includes any value metadata associated with the uset stat values.

Authorization

There is authorization logic implemented for content-isolation and access-control scenarios.

Both leaderboards and user statistics can be read from clients on any platform, provided that the caller submits a valid XSTS token with the request. Writes are limited to clients supported by the Player Data system.
Title developers can mark statistics as open or restricted with Partner Center. Leaderboards are open statistics. Open statistics can be accessed by Smartglass, as well as iOS, Android, Windows, Windows Phone, and web applications, as long as the user is authorized to the sandbox. User authorization to a sandbox is managed through Partner Center.

Pseudo-code for the check looks like this:

If (!checkAccess(serviceConfigId, resource, CLAIM[userid, deviceid, titleid]))
{
        Reject request as Unauthorized
}

// else accept request.

Required Request Headers

Header	Type	Description
Authorization	string	Authentication credentials for HTTP authentication. Example value: "XBL3.0 x=<userhash>;<token>".
X-Xbl-Contract-Version	string	Indicates which version of the API to use. This value must be set to "3" in order to include value metadata in the response.

Optional Request Headers

Header	Type	Description
X-RequestedServiceVersion		Build name/number of the service to which this request should be directed. The request will only be routed to that service after verifying the validity of the header, the claims in the authentication token, and so on. Default value: 1.

Request body

No objects are sent in the body of this request.

HTTP status codes

The service returns one of the status codes in this section in response to a request made with this method on this resource. For a complete list of standard HTTP status codes used with Xbox Live Services, see Standard HTTP status codes.

Code	Reason phrase	Description
200	OK	The session was successfully retrieved.
304	Not Modified	Resource not been modified since last requested.
400	Bad Request	Service could not understand malformed request. Typically an invalid parameter.
401	Unauthorized	The request requires user authentication.
403	Forbidden	The request is not allowed for the user or service.
404	Not Found	The specified resource could not be found.
406	Not Acceptable	Resource version is not supported.
408	Request Timeout	Resource version is not supported; should be rejected by the MVC layer.

Response body

Sample response

{
  "user": {
    "xuid": "123456789",
    "gamertag": "WarriorSaint",
    "stats": [
      {
        "statname": "Wins",
        "type": "Integer",
        "value": 40,
        "valuemetadata" : "{\"region\" : \"EU\", \"isRanked\" : true}"
      },
      {
        "statname": "Kills",
        "type": "Integer",
        "value": 700,
        "valuemetadata" : "{\"longestKillStreak" : 15, \"favoriteTarget\" : \"CrazyPigeon\"}"
      },
      {
        "statname": "KDRatio",
        "type": "Double",
        "value": 2.23,
        "valuemetadata" : "{\"totalKills\" : 700, \"totalDeaths\" : 314}"
      },
      {
        "statname": "Headshots",
        "type": "Integer",
        "value": 173,
        "valuemetadata" : ""
      }
    ],
  }
}

Share via