Skip to main content

​
Get Live Game Data

Get comprehensive live game data including quiz questions, game session, and player count.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN or quiz ID
​
api_key
string
required
User API key for authentication
​
player_count_as_a_string
boolean
default:"false"
Return player count as string instead of integer
​
in_array
boolean
default:"false"
Wrap response in array
​
in_human_count
boolean
default:"false"
Use 1-based indexing for current question (human-readable)

​
Response

​
quiz
object
Game and quiz information
  • game_id (uuid): Game session ID
  • game_pin (string): 6-digit game PIN
  • title (string): Quiz title
  • description (string): Quiz description
  • questions (array): Array of questions with answers marked as correct/incorrect
  • current_question (integer): Current question index
  • total_questions (integer): Total number of questions
  • game_mode (string): Game mode
  • started (boolean): Whether game has started
​
data
object
Game session data
  • admin (string): Admin user ID
  • game_id (string): Game session ID
  • answers (array): Array of player answers per question
​
players
object
Player count information
  • count (integer|string): Number of connected players

​
Example Response

{
  "quiz": {
    "game_id": "123e4567-e89b-12d3-a456-426614174000",
    "game_pin": "123456",
    "title": "Science Quiz",
    "current_question": 0,
    "total_questions": 10,
    "questions": [
      {
        "question": "What is H2O?",
        "type": "ABCD",
        "answers": [
          {"answer": "Water", "right": true, "color_code": "#00F007"},
          {"answer": "Oxygen", "right": false, "color_code": "#FF0000"}
        ]
      }
    ]
  },
  "data": {
    "admin": "user-uuid",
    "game_id": "game-uuid",
    "answers": []
  },
  "players": {
    "count": 5
  }
}

​
Get User Count

Get the current number of players in a game.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN or quiz ID
​
api_key
string
required
User API key
​
as_string
boolean
default:"false"
Return count as string
​
as_array
boolean
default:"false"
Wrap response in array

​
Response

{
  "players": {
    "count": 5
  }
}

​
Get Players List

Get detailed list of all players in a game session.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN
​
api_key
string
User API key for authentication
​
game_id
uuid
Alternative authentication via game ID

​
Authentication

Requires either api_key or game_id.

​
Response

Array of player objects:
​
username
string
Player’s username
​
sid
string
Socket connection ID

​
Example Response

[
  {
    "username": "Player1",
    "sid": "socket-id-123"
  },
  {
    "username": "Player2",
    "sid": "socket-id-456"
  }
]

​
Set Question

Manually set the current question number in a live game.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN or quiz ID
​
question_number
integer
required
Question index to set (0-based)
​
api_key
string
required
User API key

​
Authentication

Required - Must be the game owner

​
Response

Emits a Socket.IO event set_question_number to all connected clients with:
  • question_index: The new question index
  • question: The question data
Returns success status.

​
Get Player Scores

Get current leaderboard with player scores.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN or quiz ID
​
api_key
string
required
User API key

​
Response

Array of player scores sorted by score (highest first):
​
username
string
Player’s username
​
score
integer
Player’s total score

​
Example Response

[
  {"username": "Player1", "score": 1500},
  {"username": "Player2", "score": 1200},
  {"username": "Player3", "score": 800}
]

​
Get Current Question

Get the currently displayed question with answer markings.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN or quiz ID
​
api_key
string
required
User API key
​
in_human_count
boolean
default:"false"
Use 1-based indexing for current question

​
Response

Array containing the current question with additional metadata:
​
question
string
Question text
​
type
string
Question type (ABCD, RANGE, VOTING, etc.)
​
answers
array
Array of answers with color codes indicating correctness:
  • #00F007 for correct answers
  • #FF0000 for incorrect answers
​
current_question
integer
Current question index
​
total_questions
integer
Total number of questions

​
Example Response

[
  {
    "question": "What is the capital of France?",
    "type": "ABCD",
    "time": "30",
    "answers": [
      {"answer": "Paris", "right": true, "color": "#4A90E2", "color_code": "#00F007"},
      {"answer": "London", "right": false, "color": "#E94A4A", "color_code": "#FF0000"}
    ],
    "current_question": 1,
    "total_questions": 10
  }
]

​
Get Voting Results

Get real-time voting results for the current voting question.

​
Query Parameters

​
game_pin
string
required
6-digit game PIN or quiz ID
​
api_key
string
required
User API key
​
as_array
boolean
default:"false"
Wrap response in array

​
Response

Object with answer text as keys and vote counts as values: 
{
  "Option A": 15,
  "Option B": 23,
  "Option C": 8
}

​
API Key Authentication

All live game endpoints require an API key for authentication. You can generate an API key from the user settings page or via the /api/v1/users/api_keys endpoint.

​
Using with Game PIN

If you use a quiz ID instead of a game PIN, the system will automatically look up the active game PIN for that quiz and the authenticated user.

​
Real-time Updates

For real-time updates during a game, use Socket.IO connections. The live endpoints are designed for polling or external integrations (e.g., OBS overlays, custom dashboards).

Build docs developers (and LLMs) love

Get started for freeTalk to us