Getting started
To analyze your Riddles, you can use the Riddle Stats API to retrieve stats for any of your Riddles, projects or for your personal project.
This can help you to analyze the performance of your Riddles, to optimize them, and to get insights into your audience. Dealing with this programmatically via the API allows you to automate this process.
In the next sections we will cover different aspects and endpoints of the Stats API.
Accessing the Stats API
To learn how to access the Riddle API please refer to the Getting started guide. If you are already familiar with the API, you can find all available Stats API endpoints here.
What is tracked in the stats?
Any interaction with a Riddle is tracked. This includes views, starts, finishes, time spent, leads generated, and more. In general, everything you see on your Riddle stats dashboard is available via the API.
In addition to that project and user wide stats are tracked as well and can be requested via the API.
How can I use the stats data and which endpoints are available?
The stats endpoints serve very distinct purposes and structure the data in different ways:
- Fetch: This endpoint provides raw stats data for a single Riddle, project or user. This is useful if you want to analyze the performance of a Riddle on a high level.
- Overview fetch: This endpoint provides the raw stats data for a Riddle, project or user but splits up the given time range into multiple data points. This is useful if you want to get insights over a period of time, giving you multiple data points to analyze.
- Breakdown: This endpoint provides a detailed stats breakdown of a Riddle with all its associated labels/titles. This is useful if you want to analyze the performance of a Riddle on a low/block level and make it additionally human readable.
- Project breakdown: This endpoint provides a detailed stats breakdown of all Riddles of a project. This is useful if you want to compare the performance of multiple Riddles of a project. Running into a timeout? Try specifying a smaller time range (with
dateFromanddateToJSON params). - User breakdown: This endpoint provides a detailed stats breakdown of all user + project Riddle stats. This is useful if you want to compare the performance of multiple Riddles of various projects. Please note that this endpoint is the slowest of all breakdowns as it accumulates the most data in one response. Running into a timeout? Try specifying a smaller time range (with
dateFromanddateToJSON params).
Stats data structure
We have come up with our own format for the stats data. As your Riddle is a collection of blocks, you can think of the stats data as a combination of global stats (views, finishes) and a collection of individual block stats. Please note that this explanation is not applicable to 1.0 Riddles.
An example stats object looks like this:
{
"global_stats": {
"core_metrics": {
"view": 20,
"start": 6,
"time": 2737546,
"lead": 5,
"timeActive": 434477,
"lead_completed": 4,
"finish": 4
},
"device": {
"mobile": 8,
"desktop": 12
},
"os": {
"iOS": 8,
"Mac OS": 10,
"Windows": 2
},
"region": {
"GB": 16,
"DE": 2,
"US": 2
},
"domain": {
"riddle.com": 19,
"yourdomain.com": 1
}
},
"block_1_stats": {
"core_metrics": {
"view": 5,
"timeActive": 29583,
"submit": 5
},
"answer": {
"2": 2,
"1": 2,
"-1": 1
}
},
"block_2_stats": {
"core_metrics": {
"view": 6
},
"form": {
"submit": 5
}
},
"reset_stats": {
"core_metrics": {
"view": 6,
"start": 3,
"time": 120788,
"timeActive": 69082,
"finish": 3,
"lead_completed": 3,
"lead": 2,
"times_reset": 1
},
"device": {
"desktop": 6
},
"os": {
"Mac OS": 6
},
"region": {
"GB": 6
},
"domain": {
"riddle.com": 6
}
}
}
Let's go through the different parts of the stats object in the following sections.
Global Stats ("global_stats")
These are the global stats for the Riddle. They are not specific to a block. They can be divided into the categories:
- core_metrics: most important and easiest metrics such as views, finishes, time / timeActive (in milliseconds), ...
- device: device type (mobile, desktop, ...)
- os: operating system (iOS, Windows, ...)
- region: region with 2 chars (GB, DE, ...)
- domain: domain of the website where the Riddle was viewed. Riddle.com is the default showcase domain.
Block Stats
These are the stats for each block. They can be divided into the categories:
- core_metrics: views
- answer: the amount of times each answer was selected; to find answer IDs refer to the Riddle GET API endpoint.
- form: the amount of times the form was submitted / skipped
Reset Stats
If you choose to reset stats for a Riddle, the stats for the Riddle will be reset and the stats for the reset Riddle will be stored in the "reset_stats" object.
This makes sure no data is really lost; only hidden for the stats dashboard and the user.
FAQ / Troubleshooting
Q: Can I access stats for a date range?
A: Yes, you can access stats for a date range. To do this use the stats fetch endpoint and specify the params "dateFrom" & "dateTo" in your request.
Q: How can I access my accumulated project stats?
A: To do this you need to specify the namespace (this is project) and the project ID (param entityId) in your request to the stats fetch endpoint, example body for project 123:
{
"namespace": "project",
"entityId": 123
}
Q: How can I access Riddle stats?
A: To do this you need to specify the namespace (this is riddle) and your Riddle UUID (param entityId) in your request to the stats fetch endpoint, example body for Riddle abc123:
{
"namespace": "riddle",
"entityId": "abc123"
}
Q: How can I get insights over a period of time, giving me multiple data points to analyze?
A: To build a chart as easy as possible with the stats data you can use the overview fetch endpoint instead of the normal fetch endpoint. The difference in between those two endpoints is that the overview fetch endpoint splits up the given time range into multiple data points. E.g. if you request for a whole month (= 30 days), 15 data points will be returned with each representing two days (30 / 15 = 2).
Q: How does the Riddle / Project / user stats breakdown response look like?
An example response to the Riddle breakdown endpoint looks like this:
{
"success": true,
"code": 200,
"data": {
"general": {
"device": {
"mobile": 5,
"desktop": 3
},
"os": {
"iOS": 5,
"Windows": 2,
"Mac OS": 1
},
"core_metrics": {
"view": 8,
"lead": 4,
"start": 4,
"time": 8315,
"finish": 4
},
"domain": {
"riddle.com": 8
},
"region": {
"DE": 6,
"GB": 1
}
},
"blocks": [
{
"id": 2,
"title": "My Riddle title",
"metrics": {
"view": 0,
"time": 0,
"submit": 4
},
"choices": [
{
"id": 1,
"title": "Choice 1",
"count": 1
},
{
"id": 2,
"title": "Choice 2",
"count": 2
},
{
"id": 3,
"title": "Choice 3",
"count": 1
}
]
}
],
"results": [
{
"id": 3,
"title": "Thanks for your vote!",
"metrics": {
"view": 4
},
"socialShares": []
}
]
}
}
If you choose to request a breakdown for either a project or a full user, the response will be similar but an array of all concerned Riddles (either all project Riddles OR all user + project Riddles) will be returned.
Here's a high level overview of the structure of the response:
{
"success": true,
"code": 200,
"data": {
"RIDDLE_ID1": {
"general": {
...
},
},
"RIDDLE_ID2": {
"general": {
...
},
}
}
}