Analyze Riddles

You can use the Riddle Stats API to retrieve stats for any of your Riddles, projects or for your personal project.

FAQ

Q: How do I access this API?

A: To learn how to access the Riddle API please refer to the Getting started guide.

Q: What are the available endpoints?

A: All possible Stats API endpoints can be found here.

Q: What is tracked in the stats?

A: 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.

Q: How can I use the stats data?

A: You can use the stats data 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.

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).

Stats format (for 2.0 Riddles)

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.

Note: If you request stats for a project or user, only global stats will be returned.

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
        }
    }
}

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.

Table of Contents