Skip to main content

How to Query Cloud Save by a specific field using Client API [Mini Tutorial]

Updated

 

Scenario

You need to query or modify a specific player's Cloud Save data via the Unity Gaming Services, but you only have their Steam Nickname or another unique identifier. Because Cloud Save endpoints require a Unity Player ID, you must first resolve the player's Steam account to their Unity Player ID

 

Prerequisites

  • Unity Dashboard Service Account. Create or use a service account: Make sure you include Cloud Save Viewer and Cloud Save Editor (if required)
  • The Service Account must have the Authentication Viewer (or Editor) and Cloud Save Viewer (or Editor) roles assigned.
  • Your Service Account's Key ID and Secret Key.
  • Your UGS Project ID and Environment ID.
  • A player with data you want to fetch data from

 

Resolution:

Step 1: Cloud Save Dashboard Setup (For testing)

We are focusing on using the Steam Nickname in this example. Note that you can query any key-value pair. Normally, this information will be sent through the game/app client.

  • Head over to https://cloud.unity.com/
  • Add Cloud Save to the Shortcuts on the left of the dashboard
  • Select Cloud Save > Player Data
  • Select an existing Player
  • Under Default Tab
  • Select Add Key Value Pairs
  • Choose a Key. In this example, we will call it steamPlayerName. 
  • Add the Value "MySteamNickName"
  • Select Add at the bottom right of the screen

Step 2: Configure Indexes

Before we can query, we need to set up indexes.

  • Select Cloud Save from the shortcuts
  • Select Configure Indexes
  • Click on Create Index
    • Set Entity Type Players
    • Set Access Class Default. 
    • Set the key to steamPlayerName
  • Click Create to create the index.

 

 

Step 3: API Client Setup

Configure Basic Authentication to retrieve token
The Unity Client APIs require Basic Authentication. For Cloud Save, we need to capture a bearer token. We can get that using the Token Exchange 
  • Open your API client (e.g., Postman) and navigate to the Authorization tab.
  • Set the Auth Type to Basic Auth.
  • Enter your Service Account Key ID in the Username field.
  • Enter your Service Account Secret Key in the Password field.
  • Change to a POST request
  • https://services.api.unity.com/auth/v1/token-exchange?projectId={{ProjectId}}&environmentId={{EnvID}}
  • Replace
  • Replace {{EnvID}}  with your environment ID,
  • Click SEND or equivalent in your Client API. This should give you a bearer token. The token will be used in the next API call and is valid for 1 hour. Copy the token for use in the next step.

 

 

Query Cloud Save

  • Create a new request
  • Set the Auth Type to Bearer Token
  • Enter your Token that you previously created
  • Change to a POST request
  • https://cloud-save.services.api.unity.com/v1/data/projects/{{ProjectId}}/players/query

    **If you wish to query Public data, simply add /players/public/query at the end of the POST

  • Replace 

  • {
 "fields": [
   {
     "key": "steamPlayerName",
     "value": {"MySteamNickName"},
     "op": "EQ",
     "asc": true
   }
 ],
 "returnKeys": [
   "steamPlayerName"
 ],
 "offset": 0,
 "limit": 100,
 "sampleSize": 100
}

  • Click SEND or equivalent in your Client API. This should give you the Unity Player ID, which can now be used to search in the Unity Dashboard.

        "results": [
        {
            "id": "F7e4R3WBeFpW3Q5Lpom02yV2IeFq",
            "data": [
                {
                    "key": "steamid",
                    "value": "MySteamNickName",
                    "writeLock": "d4456b0859b4e8f04018edc007caeaa40",
                    "modified": {
                        "date": "2026-04-14T14:27:45Z"
                    },
                    "created": {
                        "date": "2026-04-10T19:31:21Z"
                    }
                }
            ]
        }
    ]
}


     

 

Conclusion

This is the simplest way to quickly retrieve a player's Cloud Save data using the API. You can combine this with cloud code and client code to automate. This will be covered in a later tutorial.


 

 

Related to

Related articles