Riddle Stats API

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

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

Fetching stats for a date range

To get accumulated stats for a given date range, use the fetch endpoint.

Table of Contents