Guide to Kahoot! reports API

Wondering how to use Kahoot! reports API? Here's everything you need to know to get started.

Shortcuts:

• About the Kahoot API
• How to access the API
• Authenticating with the API
• Glossary
• Common Requests - How To Guide

About the Kahoot API 

The  Kahoot API is a REST API that follows OpenAPI. You can review all of our API documentation including details of the resources and endpoints at  https://results.kahoot.com/swagger/. 

In order to make calls to Kahoot API your company will require authorized access. The API is best for customers who have either a data team or developers who are familiar with APIs. With this API your company will be able to access all data listed below within the last 90 days after the game finishes. We timestamp our data and support start and end dates for when the customer pulls the data from our system. 

The Kahoot API reports on information pertaining to the game, users, participants, organizations, and kahoots created by the organization. Sometimes, our reporting on the platform can only do so much. For customers who use the product frequently or with a high number of participants, and want to track their activity, the API is a great way to do that scalably.

How to access the API

Authorization of the API is only available to customers on certain highest-tier plans. Reach out to your customer success manager if you are interested in either upgrading or initiating the authorization process.

Authenticating with the API

Authentication for the API is achieved through the use of a JWT bearer token which should be provided in the Authentication header of each request to the API. Tokens are time limited to an hour after which a new token must be obtained.

To obtain a token you will first need a client id and secret which will be provided by your customer success manager. Once you have these credentials you must request the token from our authentication server as described below.

URL	https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token
Http Method	PUT
Authorization Header	Should provide basic authorization heading using the credentials provided by kahoot.
Content-Type Header	application/x-www-form-urlencoded
Body of Request	grant_type=client_credentials

 

An example request that could be made with curl is shown below:

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Authorization: Basic <digest>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials

 

The response from the request will have the following structure:

{
"access_token": "<token to use in api requests>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

 

To properly authenticate to the API you must use the value of the access_token in the above response as a bearer token in your requests to the API. This means that the Authorization header of all requests should have the value in the form of “Bearer: <token>”. If you have not correctly provided a valid token to the API a 401 response will be returned.

Glossary

Term	Description
Live Game	When a kahoot is played in person.
Challenge	When a kahoot is played asynchronously.
points	Integer value. The number of points the player got for this question.
answers	A set of submitted answers for a question.
received, timeout	The answer provided for the question.
timeout	When a user did not provide an answer to a question.
Block	Specific types of questions are always referred to as 'block' for example - the True or False question type is called TrueFalseBlock and the Brainstorm question type is referred to as BrainstormBlock.
kahoot	The actual kahoot. This is different than a game or game session (what we call when the kahoot is actually played).
game	When the kahoot is played.
game session	A unique game instance.
host	The user who launched the game.
kahoot version	If kahoots are modified we store different versions of that kahoot. Different versions of a kahoot may be played and thus have different answers stored. The version of the kahoot where 0 is indicated is not versioned.
course	Some games are tied to courses, if this is the case there will be a course ID provided.
Block index - Kahoot	Index at which the game originally appeared in the associated kahoot (0-based).
Block index - Game	Index at which the game appeared during the game session (0-based). Can be different than blockIndexInKahoot in case of random order of questions was used.
questions	List of questions in the kahoot.
Brainstorm (question type)	Open-ended question type where participants submit ideas and vote.
Drop Pin (question type)	Question with no points where participants can drop pins on an image.
Poll (question type)	Question with no points where players choose up to 6 options in a question.
Multiselect Quiz (question type)	Give players several answers to choose from in a question.
Open Ended (question type)	Question for players to answer in a long-form text response.
Puzzle (question type)	Question where players put answers in the correct order.
Slider (question type)	Participants guess the correct number in a range.
True False (question type)	Participants decide if a statement is true or false.
Type Answer (question type)	Participants answer with a short form text.
Word Cloud (question type)	Question that collects short free-form poll questions.

Common Requests - How To Guide

• How to list participants of a game
• Who is a “participant”? 
• Find the game
• What is the difference between participantId and userId? 
• How to get participant’s e-mail address
• How to list participants who got at least 80% questions right
• What if 404 is returned? 
• Matching answers with participants 
• What does “correct answer” mean?
• Relationship between timed-out and correct answer 

How to list participants of a game

Who is a “participant”? 

The following steps describe how to list all players who entered the game. 

Please note that “joining” is not the same as “actively playing”. It is possible to join the game and not answer any questions because of connection issues or not paying attention. Such participants are still going to be included in the results. 

Find the game 

Invoke GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} to list all games played in your organization in a given time frame. Add cursor query parameter in case another page of results is available and needed.

A sample output will contain a list of game sessions: 

{
data: [
 "gameSessionId": "3c28c370-0407-416f-a44f-087715b4ea89",  "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358",  "kahootIdentifier": { 
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "version": 5 
 }, 
 "startTime": 1667928438123, 
 } 
 ], 
 cursor: "abcxyz" 
}

Find the session in the results and remember it’s gameSessionId. 

List participants of the game 

Invoke GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants to list all participants who joined the game.

Sample result: 

[ 

 { 

 "participantId": 1234, 

 "nickname": "Johnny", 

 "userId": "f7e9a793-f223-4f2e-ad79-8bfa546a7180" 

 }, 

 { 

 "participantId": 4321, 

 "nickname": "Robert", 

 "userId": "a9555f0c-68b2-41b1-a540-49c34e15242e" 

 } 

]

What is the difference between participantId and userId? 

• participantId is an integer and is always present regardless of the game options.
• participantId identifies given player within this game session only. Same participantId in a different game session may and  usually does refer to a different person. 
• userId is only included in games with the Player Identifier option enabled. That is when the players are asked to provide their credentials such as e-mail in addition to the nickname. Or when they are invited to the game using their e-mails.
• userId makes it possible to track the same person across multiple game sessions.

How to get participant’s e-mail address 

Invoke GET /v1/organisations/{organisationId}/users/{userId} The returned object will contain email property. 

How to list participants who got at least 80% questions right 

Find the game

See the section about finding the game. 

Find the information about the kahoot that was played. It has two parts: 

1. id - UUID referencing the kahoot that was played 

2. version - the kahoot might have been edited by the creator after the game took place. Each time that happens it gets the version property incremented. This ensures that the answers refer to correct data. 

{ 

 // other propperties 

 "kahootIdentifier": { 

 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 

 "version": 5 

 }, 

}

Get participants

See the section on listing the participants.

Get kahoot data 

Invoke GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} to get the kahoot with query parameters based on kahootIdentifier.id and kahootIdentifier.version properties. 

The result is going to contain all questions (blocks) contained by the kahoot alongside the answer choices that were available to the participants if applicable. Questions and answer choices are going to be later referenced by the answer documents. 

Sample questions: 

{ 

 "kahootIdentifier": { 

 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 

 "version": 5 

 }, 

 "title": "Kahoot title", 

 "description": "This kahoot is about ...", 

 "questions": [ 

 { 

 "contentType": "CONTENT" 

 "blockIndex": 0 

 "title": "This is the company presentation" 

 "description": "Some slide contents" 

 }, 

 { 

 "contentType": "SINGLE_SELECT_QUIZ" 

 "blockIndex": 1 

 "question": "Who is our biggest customer?" 

 "choices": [ 

 {"answerText": "Very Big Corp. of America", "correct":  false}, 

 {"answerText": "Skynet", "correct": true} 

 ] 

 }, 

 ] 

}

Get all answers 

Invoke GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers using gameSessi onId obtained when looking for the game (see find game section) and blockIndex being index of the question in the kahoot. One needs to iterate over all blocks (questions) that were played, excluding the ones that weren't questions at all (content aka. slides). 

The following example shows an answer to the second block of the kahoot which was a single select quiz, where the participant identified with parti cipantId=1234 (nickname “Johnny” as in the listing participants example) and selected the second choice which happened to be correct. We can also see that the participant with the nickname “Robert” didn’t manage to answer the question within the time limit.

{ 

 "blockIndexInKahoot": 1 

 "answers": [ 

 { 

 "participantId": 1234, 

 "answerStatus": "RECEIVED", 

 "answer": { 

 "type": "SINGLE_SELECT_QUIZ", 

 "choice": 1, 

 "correct": true, 

 "points": 900 

 } 

 }, 

 { 

 "participantId": 4321, 

 "answerStatus": "TIMEOUT" 

 }, 

 ] 

}

In order to know what was the choice and what was the participant's nickname one need to refer to related kahoot data and the participant's data mentioned in previous sections. 

What if 404 is returned? 

The answers for a given block can be missing in the following cases: 

1. Given question (block) is of type CONTENT. "Answering" them is not well-defined. 
2. The game was played as an assignment and none of the participants reached that question 3. 
3. There was a network issue during the gameplay and the answer wasn’t saved (rare case, but possible to happen).

In any case, the clients need to be prepared that the answer data may be missing there. 

Matching answers with participants 

Answers contain only the links to the participants whose details are contained in separate endpoint’s response payload (see “List participants of the game” section). That link is participantId property present in both payloads. 

What does “correct answer” mean? 

In the case of some question types, there exists some gray area between “incorrect” and “correct” answer status.

Multiple-select quiz questions 

CORRECT - the participant selected all correct choices and none of the wrong ones 

PARTIALLY_CORRECT - the participant selected at least one of the correct choices and none of the wrong ones WRONG - the participant selected at least one of the wrong choices 

Slider questions 

CORRECT - the participant selected the correct value on the slider 

ALMOST_CORRECT - the participant selected a value that wasn't exact, but within the tolerance set by the kahoot creator WRONG - the selected value was outside the tolerance range

All other questions 

For all other questions that can have right or wrong answers, there are only two choices: CORRECT and WRONG.

Relationship between timed-out and correct answer 

ParticipantAnswer objects with status equal to TIMEOUT are not going to have answer property, so they are neither "correct" nor "wrong".  It is up to the user to decide how to treat them. They’re always assigned zero points during the game.