Smarterer API


Get a list of badges for either a specified username or, if no username is specified, the currently authenticated OAuth user.

optionally Query for a specific badge or set of badges


  • /api/badges: Get badges for the user currently logged-in via OAuth. Requires authorization as a user.
  • /api/badges?tests={test_url},{test_url}: Get badges for the user currently logged-in via OAuth and filter for only specific tests. Requires authorization as a user. The list of tests are each identified by their Smarterer test "url_slug" and are comma separated with no spaces. If the user has no badge for a requested test no result will be returned for that test.
  • /api/badges/{username}:

    marked for deprecation

    Get public badges for a user by Smarterer username. User authorization (access_token) is not required.

    note: Smarterer scores (badges) are now private so only legacy users will show public badges


User oauth access token for whom the request is being made.
A comma separated list of Smarterer test url_slugs to match against. Only badges matching these tests / url_slugs will be returned.

API Response


    "username": "someuser",
    "badges": [
            "badge": {
                "image": "", 
                "is_public": true, 
                "last_modified": "2013-03-13T15:06:53", 
                "level": "Proficient", 
                "min_threshold": true, 
                "percentile": 66.87, 
                "raw_score": 534.975, 
                "score": 535
            "quiz": {
                "id": 44, 
                "name": "Python", 
                "url_slug": "python"
            "state": "out_of_questions"
            "badge": {
                "image": "", 
                "is_public": true, 
                "last_modified": "2012-02-12T22:23:42", 
                "level": "", 
                "min_threshold": false, 
                "percentile": 30.28, 
                "raw_score": 242.212, 
                "score": 242
            "quiz": {
                "id": 51, 
                "name": "PHP", 
                "url_slug": "php"
            "state": "running"

Response Structure

The response is JSON containing the following keys:
  • username: a string
  • badges: a list of objects with the following keys:
    • state: the last known state of the users test session as a string, one of "practice", "practice_running", "practice_done", "running", "idle", or "out_of_questions". The state "out_of_questions" means that the user does not currently have any questions available to answer in this test.
    • badge: an object with the following keys:
      • image: absolute URL to an image showing this score badge
      • score: numeric score, rounded to nearest integer. This score is recommended for display use.
      • raw_score: numeric score as a floating-point number. This score is not recommended for display.
      • level: named level for the current score, typically "Beginner", "Familiar", "Proficient", "Expert", or "Master" (see How Scoring Works). If the user has not attained one of these named levels, the value of this key will be blank.
      • min_threshold: a boolean flag indicating that the user has crossed an internal high watermark indicating that the score error has been reduced to a reasonable level.
      • percentile: the users percentile score against the population at the time when the score was last computed
      • last_modified: ISO 8601 datetime, the last time that the user requested a new question in this test.
      • is_public: boolean, whether this badge is publically visible. (private badges are only available to their owners; Requires OAuth login.)
    • quiz: an object with the following keys:
      • name: a string indicating the human-readable name for this test.
      • id: the unique numeric ID of this test within Smarterer.
      • url_slug: the unique URL slug for this test within Smarterer.