List surveys

GET /v1/player/surveys · for player session

Use it to show the community's surveys inside the game: after a match, from a menu, or wherever a question fits. Send the player session as the bearer token. The request needs the game loop. For the three conditions (game loop enabled for the game, member consent, server membership) and the error each returns, see What has to be true first.

A survey is listed when the community's team switched on In game for it in Surveys & Forms, for this game or for every game, and:

• it is taking responses (open, not paused, not closed and under its response limit);
• it is open to the member: a survey limited to a role waits until CEEJAY can read the member's roles;
• the member has not finished it;
• for a survey that waits for a game event, the game has logged that event for the player, with Log player events, the number of times the team set since the survey opened;
• every required question is one a game can ask. A survey with a required member picker or file upload is answered in Discord and is not listed.

Query parameters

Returns

data is a list of surveys, newest first. The response also includes page, with nextCursor and limit.

Each question in questions contains:

How to ask each type

Paging

Pass page.nextCursor as cursor and stop when it is null. A survey can leave the list between two calls (it closed, or the player finished it), so key the list by the survey's id.

Example

curl "https://ceejay.communitystudios.xyz/api/v1/player/surveys?limit=10" \
  -H "Authorization: Bearer $CEEJAY_PLAYER_SESSION"

The TypeScript example uses connect.hub.listSurveys from the Connect client in the TypeScript SDK. The player must be connected first: the client manages and refreshes the player session. It returns the full response below, with the list in data.

{
  "success": true,
  "data": [
    {
      "id": 41,
      "title": "Tonight's playtest",
      "description": "Three quick questions about the build you played.",
      "questions": [
        {
          "key": "k_00000000000000a1",
          "label": "How would you rate the build?",
          "type": "rating",
          "required": true,
          "placeholder": null,
          "description": null,
          "options": [
            { "label": "1", "value": "1" },
            { "label": "2", "value": "2" },
            { "label": "3", "value": "3" },
            { "label": "4", "value": "4" },
            { "label": "5", "value": "5" }
          ],
          "minLength": null,
          "maxLength": null,
          "minChoices": null,
          "maxChoices": null,
          "scale": { "low": "Poor", "high": "Great", "icon": "number" }
        },
        {
          "key": "k_00000000000000a3",
          "label": "What should we change?",
          "type": "text_long",
          "required": false,
          "placeholder": null,
          "description": null,
          "options": [],
          "minLength": null,
          "maxLength": 1000,
          "minChoices": null,
          "maxChoices": null,
          "scale": null
        }
      ],
      "closesAt": null,
      "rewards": { "xp": 50, "roles": 0, "names": ["20 coins"] }
    }
  ],
  "page": { "nextCursor": null, "limit": 10 }
}

Limits

120 reads a minute for one player session, shared by every request of the game loop that reads. Every request made with a player session also counts toward 140 a minute. See Rate limits. Over a limit the response is 429 with the code rate_limited, retryAfter and a Retry-After header.

Errors

Every error body also includes requestId. Match on code; message text can change.

The errors every request of a game shares (the key, the state of the game, the origin, 405, 429, 500) are on the Errors page, and the errors specific to the game loop are under Codes of the game loop.