Sessions Endpoints

The Data API's session endpoints allow you to programmatically retrieve and operate on the raw assessment data of your learners.

You would want to use this for data warehousing and for specialized reporting on the content, status and scoring of learner sessions.

Usage

The format of requests to Data API use the following syntax:

https://data.learnosity.com/[LTS_VERSION]/sessions/*

For example, to use the 2023.3.LTS version and the 'Responses' sessions endpoint, you would create a request like so:

https://data.learnosity.com/v2023.3.LTS/sessions/responses

Responses

Returns learner responses and scores per session.

• The dt_score_updated (date time of the latest score change) value returned with each response object shows the time of the most recent update to the response record, resulting from a save, submit, auto-scoring, or manual scoring operation. This attribute will be updated only if there is an actual change in score value.

{
    "include": {
        "sessions.session_metadata": ["my_existing_field"]
    }
}

Example

{
    "activity_id": [
        "numeracy",
        "writing"
    ],
    "user_id": [
        "aeee19fb-4e7b-435c-92f9-d93a1099988b",
        "ee647f28-953a-4325-94fe-4a5083b7545b"
    ]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389202121,
    "next": "1387312240.1410",
    "records": 1
  },
  "data": [
    {
      "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b",
      "activity_id": "numeracy",
      "num_attempted": 1,
      "num_questions": 2,
      "session_id": "340BF0ED-77B0-45D0-A81EBE2F69DB51C1",
      "score": 0,
      "subscores": null,
      "session_duration": 1714,
      "status": "Completed",
      "dt_started": "2023-03-03T12:23:35Z",
      "dt_completed": "2023-03-04T16:57:15Z",
      "responses": [
        {
            "response_id": "340BF0ED-77B0-45D0-A81EBE2F69DB51C1_sbalancedtestg3q1",
            "question_type": "imageclozeassociation",
            "dt_score_updated": "2023-03-03T12:30:21Z",
            "automarkable": false,
            "response": null
        },
        {
            "response_id":"DC03CFD5-D56D-4B2C-962D0926D0046B9D_sb3q12_1",
            "question_type":"longtextV2",
            "dt_score_updated": "2023-03-03T12:33:03Z",
            "automarkable": false,
            "response":{
                "value":"parallelogram is a quadrilateral with two pairs of parallel sides.",
                "wordCount":33,
                "type":"string",
                "apiVersion":"v2.6.0"
            }
        },
        "items": [
            {
                "reference": "340BF0ED-77B0-45D0-A81EBE2F69DB51C1_sb3q1",
                "time": 85,
                "response_ids": [
                    "340BF0ED-77B0-45D0-A81EBE2F69DB51C1_sb3q1"
                ]
            },
            {
                "reference": "DC03CFD5-D56D-4B2C-962D0926D0046B9D_sb3q12_1",
                "time": 65,
                "response_ids": [
                    "DC03CFD5-D56D-4B2C-962D0926D0046B9D_sbalancedtestg3q12_1"
                ]
            },
            {
                "reference": "357378865",
                "response_ids": [
                    "B6F208AF-6D37-4ACC-93F9AAF53AE9DEBC_a80df0232c04743346841d793e8b4df6"
                ],
                "time": 70,
                "user_flagged": false,
                "scoring": {
                    "score": 0,
                    "max_score": 1,
                    "type": "per-question"
                }
            }
        ],
        "metadata": {
            "activity_template_id": "numeracy-test",
            "items_api_version": "v1.66.0",
            "max_time": 1500,
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36"
        }
      ]
    }
  ]
}
*/

Calculating the session duration

There are two ways to calculate the session time spent by the learner. The first is the value returned by the endpoint called session_duration. The second is to manually calculate the active time spent on each Item.

Using session_duration

The session_duration value represents the time in minutes (rounded up), between when the session was started (dt_started) and when the session was completed (dt_completed). If the session was saved, and then later resumed, the session_duration will include the number of minutes when the session was in a saved state.

From the session_duration, the server calculated time is 1714 minutes (28.6 hours) based on the started and completed timestamps. However, not all of this time was active because the session was saved and resumed the following day.

Using the time spent per Item

The time value for each Item is measured in seconds. The timer starts when the learner navigates to an Item and stops when the learner navigates away from it. Pausing the Activity will also stop the timer. Moving to a different tab in the browser does not pause the timer, the time will continue to be recorded even though the tab is inactive.

To calculate the session duration manually, you can add all of the individual Item time values from each Item response data. From the above response example, to find the active working time spent on the session, ignoring when it was saved, add together the time (in seconds) spent on each Item. Running the calculation for the above example, the total time spent is: 85 + 65 + 70 = 220 seconds.

From the Item time calculation, we see that the total active time spent by the learner is 220 seconds or 3.67 minutes.

Scores

Retrieves the learner scores per session. The learner's response content is not returned in the results.

Example

{
    "user_id": [
        "17c456c0-89ad-4f72-8010-2f7d991f54bd",
        "ba281305-8afb-40de-8378-10a2bffb8024"
    ]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389202121,
    "next": "1387312240.1410"
  },
  "data": [
    {
      "user_id": "17c456c0-89ad-4f72-8010-2f7d991f54bd",
      "activity_id": "chemistry_classtest1",
      "session_id": "4d3115f0-1235-4613-5be6fc6e6b2e",
      "score": 39,
      "max_score": 40,
      "subscores": [
        {
          "id": "subscore-1",
          "title": "biochem",
          "num_questions": 20,
          "num_attempted": 20,
          "score": 19,
          "max_score": 20,
          "attempted_max_score": 20,
          "items": [
            "293486384",
            "293481468",
            "293475858",
            "293475234",
            "292922805"
          ]
        }
        {
          "id": "subscore-2",
          "title": "inorganics",
          "num_questions": 20,
          "num_attempted": 20,
          "score": 20,
          "max_score": 20,
          "attempted_max_score": 20,
          "items": [
            "293486384",
            "293481468",
            "293475858",
            "293475234",
            "292922805"
          ]
        }
      ],
      "status": "Completed"
    },
    {
      "user_id": "ba281305-8afb-40de-8378-10a2bffb8024",
      "activity_id": "economics_classtest1",
      "session_id": "60c527f3-f426-4f22-f1808cbee8f8",
      "score": 2,
      "max_score": 40,
      "subscores": [
        {
          "id": "subscore-1",
          "title": "micro",
          "num_questions": 20,
          "num_attempted": 6,
          "score": 1,
          "max_score": 20,
          "attempted_max_score": 6,
          "items": [
            "293477143",
            "293477147",
            "293477148",
            "293477158",
            "293477161"
          ]
        }
        {
          "id": "subscore-2",
          "title": "macro",
          "num_questions": 20,
          "num_attempted": 3,
          "score": 1,
          "max_score": 20,
          "attempted_max_score": 3,
          "items": [
            "293728912",
            "293728916",
            "293728917",
            "293728922",
            "293728931"
          ]
        }
      ],
      "status": "Completed"
    }
  ]
}
*/

Response Scores

Returns learner responses and scores per session without Item information. To include Item information, see the /sessions/responses endpoint.

• The dt_score_updated (date time of the latest score change) value returned with each response object shows the time of the most recent update to the response record, resulting from a save, submit, auto-scoring, or manual scoring operation. This attribute will be updated only if there is an actual change in score value.

Example

{
    "session_id": [
        "4d3115f0-1235-4613-5be6fc6e6b2e"
    ]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389202121,
    "next": "1387312240.1410"
  },
  "data": [
    {
      "user_id": "17c456c0-89ad-4f72-8010-2f7d991f54bd",
      "activity_id": "chemistry_classtest1",
      "session_id": "4d3115f0-1235-4613-5be6fc6e6b2e",
      "score": 39,
      "max_score": 40,
      "subscores": [
        {
          "id": "subscore-1",
          "title": "biochem",
          "num_questions": 20,
          "num_attempted": 20,
          "score": 19,
          "max_score": 20,
          "attempted_max_score": 20,
          "items": [
            "293486384",
            "293481468",
            "293475858",
            "293475234",
            "292922805"
          ]
        }
        {
          "id": "subscore-2",
          "title": "inorganics",
          "num_questions": 20,
          "num_attempted": 20,
          "score": 20,
          "max_score": 20,
          "attempted_max_score": 20,
          "items": [
            "293486384",
            "293481468",
            "293475858",
            "293475234",
            "292922805"
          ]
        }
      ],
      "status": "Completed",
      "responses": [
        {
            "response_id": "2571d802-0095-4d66-94bc-4cfa44b0ebbe",
            "dt_score_updated": "2017-06-19T02:03:19Z",
            "score": 1,
            "max_score": 1,
            "item_reference": "293486384"
        },
        {...}
    }
  ]
}
*/

Update Response Scores

Updates individual response scores within a single session.

Example

{
    "sessions": [
        {
            "session_id": "33AF8034-8DFF-4C20-80D1E93AF1B1A573",
            "user_id": "17c456c0-89ad-4f72-8010-2f7d991f54bd",
            "responses": [
                {
                    "response_id"     : "33AF8034-8DFF-4C20-80D1E93AF1B1A573_l_cc_widget5",
                    "score"           : 3.5,
                    "max_score"       : 5.0,
                    "manual_score"    : 2,
                    "max_manual_score": 3
                },
                {
                    "response_id"     : "33AF8034-8DFF-4C20-80D1E93AF1B1A573_parcc_ela6-8_3",
                    "score"           : 0.4,
                    "max_score"       : 1,
                    "manual_score"    : 0,
                    "max_manual_score": 0.5
                }
            ]
        }
    ]
}

/* Example Response:
{
    "meta":{
        "status":true
    },
    "data":{
        "job_reference": "9fd443d0-2b4f-4315-aec6-708da3d30d49"
    }
}
*/

Statuses

Returns information about a session, such as, when it was started, has it been completed, many Questions were attempted, and so on.

Note: session statuses can be updated with the UPDATE /jobs/sessions/statuses endpoint.

"include": {
    "sessions": ["activity_template_id"]
}

Example

{
  "session_id": [
    "0a643076-1161-4aef-bf59-a5126a72a403",
    "15658ed8-c334-4697-a860-6f1997ac19f8",
    "c67687d8-cd2a-41e1-a3a3-769f334833b1"
  ],
  "include": {
    "sessions": [ "activity_template_id" ]
  }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1469590890,
        "next": "1469536296.323078",
        "records": 3
    },
    "data": [
        {
            "user_id": "d7dd0d99-a2da-48f6-8e51-f938cf65204e",
            "activity_id": "templated_assessment",
            "num_attempted": 10,
            "num_questions": 10,
            "session_id": "0a643076-1161-4aef-bf59-a5126a72a403",
            "session_duration": 7,
            "status": "Completed",
            "dt_started": "2016-07-26T23:31:02Z",
            "dt_completed": "2016-07-26T23:38:06Z",
            "activity_template_id": "demo_assessment_template"
        },
        {
            "user_id": "ca5ca132-ef22-4e31-9c74-f5ae9ace2004",
            "activity_id": "demo_assessment",
            "num_attempted": 9,
            "num_questions": 10,
            "session_id": "15658ed8-c334-4697-a860-6f1997ac19f8",
            "session_duration": 8,
            "status": "Discarded",
            "dt_started": "2016-07-26T23:25:30Z",
            "dt_completed": "2016-07-26T23:33:50Z"
        },
        {
            "user_id": "9a582c41-100c-40a2-be95-48fa5446bb7e",
            "activity_id": "demo_assessment",
            "num_attempted": 0,
            "num_questions": 10,
            "session_id": "c67687d8-cd2a-41e1-a3a3-769f334833b1",
            "session_duration": ,
            "status": "Incomplete",
            "dt_started": "2016-07-27T00:31:45Z",
            "dt_completed": null
        }
    ]
}
*/

Reports for Adaptive Tests

Returns a report for sessions attempted with adaptive Items.

For a session taken via the self-hosted adaptive flow, this endpoint's response will include the custom_state data recorded for that session.

Example

{
    "activity_id": [
        "CCASWinter14G06AVE"
    ]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1399598503,
    "next": "1395250200.452010",
    "records": 1
  },
  "data": [
    {
      "meta": {
        "status": true
      },
      "user_id": "cacf6e44-0819-4f13-bcca-833077aa96e1",
      "activity_id": "activity_101",
      "num_attempted": "2",
      "num_questions": "10",
      "session_id": "F9CE1BCC-8063-49AB-9381C8C4E4EED59E",
      "score": 0,
      "session_duration": "4",
      "status": "Completed",
      "dt_started": "2014-04-28T03:02:00Z",
      "dt_completed": "2014-04-28T03:05:40Z",
      "adaptive": {
        "ability_estimate": {
          "ability_estimate": -2.7108152670834,
          "standard_error": 0.26591405064314
        },
        "items": null,
        "exposed_items": {
          "operational": [
            "317816404",
            "317784096",
            "317802868",
            "288959069",
            "288983212",
            "288908402",
            "290095962"
          ],
          "seeding": [
            "368259876",
            "368256055",
            "368292926"
          ]
        }
      }
    }
  ]
}
*/

Get Templates

This endpoint can be used to create a session template JSON, which is a standardized base learner session which can be used many times to generate empty sessions. This session template should correspond to a set of Items or an Activity. It can contain information such as the Items in the assessment, the scoring type to be used, subscore settings, and so on.

You would want to use this together with the SET sessions endpoint to generate learner session data in order to test and preview your reports using Reports API, for example. This endpoint can also be used to generate sessions for paper based assessments.

Note: at this stage, there is no need to provide a user_id, activity_id, session_id, or adaptive object, because these details must be provided per session in the second part of this process when calling SET sessions endpoint.

Example

{
    "activity_template_id": "demo-activity-1",
    "items": [ "demo-mcq-1" ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1497929012,
        "records": 3
    },
    "data": {
        "items": [
            {
                "reference": "demo-mcq-1",
                "source": {
                    "reference": "demo-mcq-1",
                    "organisation_id": 1
                },
                "content": "<div class=\"row\"><div class=\"col-xs-12\"><span class=\"learnosity-response question-91c92c18e3725773844d8acaf12303ae\"></span></div></div>",
                "metadata": {
                    "acknowledgements": null,
                    "scoring_type": "per-question"
                },
                "workflow": [],
                "feature_ids": [],
                "question_ids": [
                    "91c92c18e3725773844d8acaf12303ae"
                ]
            }
        ],
        "metadata": {
            "items_api_version": "latest",
            "activity_template_id": "demo-activity-1"
        },
        "questions": [
            {
                "options": [
                    {
                        "label": "Cow",
                        "value": "0"
                    },
                    {
                        "label": "Horse",
                        "value": "1"
                    },
                    {
                        "label": "Chicken",
                        "value": "2"
                    },
                    {
                        "label": "Crocodile",
                        "value": "3"
                    }
                ],
                "stimulus": "Which of the following animals are mammals?",
                "type": "mcq",
                "multiple_responses": true,
                "validation": {
                    "scoring_type": "exactMatch",
                    "valid_response": {
                        "score": 1,
                        "value": [ "0", "1" ]
                    }
                },
                "ui_style": {
                    "type": "horizontal"
                },
                "metadata": {
                    "valid_response_count": 1,
                    "sheet_reference": "demo-mcq-1",
                    "widget_reference": "7578fd36-97ac-4648-babc-0b0d37b69e69",
                    "source": {
                        "organisation_id": 1
                    }
                },
                "id": "91c92c18e3725773844d8acaf12303ae"
            }
        ]
    }
}
*/

Failed Submissions

This endpoint can be used to submit failed learner submissions.

You would want to use this to re-submit a learner's session that could not be saved or submitted due to network issues, for example.

See Configuring Behavior in Case of Network Failure & Failed Submission for more information on how a learner can obtain their session data.

The endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs endpoint and the returned job_reference to check the status of the job.

Example

{
    "data_format": "failed_submission",
    "data": [
        "[BASE64 ENCODED SESSION 1]",
        "[BASE64 ENCODED SESSION 2]",
        "[BASE64 ENCODED SESSION 3]",
        "[BASE64 ENCODED SESSION 4]"
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1433375442
    },
    "data": {
        "job_reference": "58023cd7-3158-4b47-9708-34f976466cd7"
    }
}
*/

Template Submission

This endpoint supports the programmatic creation of new sessions. The endpoint accepts a template object retrieved from the GET sessions/templates endpoint, and one or more sets of learner responses for the Items contained in that template.

You would want to use this to set up and prepare sessions for paper based assessments, for example.

The endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs endpoint and the returned job_reference to check the status of the job.

The following Question types are supported: association, choicematrix, clozeformula, clozeinlinetext, clozetext, formulaV2, gridded, longtext, longtextV2, mcq, orderlist, plaintext, and shorttext . Contact Learnosity Support if you want to use other Question types not listed above.

Example

/**
 * Example session submission for an Activity containing a multi-select MCQ, a shorttext and a plaintext response.
 */
{
    "data_format": "from_template",
    "template": {
        /* Template returned by the GET session/template endpoint */
    },
    "data": [
        {
            "user_id": "1f4b4e68-5986-4468-90da-50f9901cc7ae",
            "activity_id": "example-paper-based-activity",
            "session_id": "cb6ffc66-8fdb-4beb-a712-cffc31725e57",
            "responses": [
                /* mcq, clozetext or clozeinlinetext */
                {
                    "question_id": "91c92c18e3725773844d8acaf12303ae",
                    "type": "array",
                    "value": [
                        "0", "1"
                    ]
                },
                /* shorttext */
                {
                    "question_id": "3f45ee6e3d2e4ca2b3a84df3c53c45a6",
                    "type": "string",
                    "value": "makka+pakka",
                    "characterCount": 11
                },
                /* longtextV2, plaintext or longtext */
                {
                    "question_id": "811c7d8cd2f870eaa7ba922ba622e9",
                    "type": "string",
                    "value": "upsy+daisy"
                    "wordCount": 2
                },
                /* gridded */
                {
                    "question_id": "7578fd3697ac4648babc0b0d37b69e69",
                    "type": "string",
                    "value": "1234.56"
                },
                /* choicematrix */
                {
                    "question_id": "AC745C70FEC74331AA8A829D066BD06E"
                    "type": "array",
                    "value": [[0, 1], [0], [1], [0]]
                }
            ]
        }
    ]
}
/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1497929288
    },
    "data": {
        "job_reference": "248966d0-b1a3-4c0b-a569-76423d7cae74"
    }
}
*/

Session Metadata

Retrieves the metadata that was previously set from the specified sessions.

You would want to use this to process all session metadata for your application, for example.

The session metadata can be added and updated with the SET /jobs/sessions/metadata endpoint.

• The dt_score_updated (date time of the latest score change) value returned with each response object shows the time of the most recent update to the response record, resulting from a save, submit, auto-scoring, or manual scoring operation. This attribute will be updated only if there is an actual change in score value.

Example

{
    "session_id": [
        "9ce7daeb-e117-4d14-9452-c94a0afe203b"
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1522209399,
        "next": "1522209397.443887",
        "records": 1
    },
    "data": [
        {
            "user_id": "422ecd28-870b-4037-a365-f45153851ce6",
            "session_id": "9ce7daeb-e117-4d14-9452-c94a0afe203b",
            "metadata": {
                "session_tags": [
                    {
                        "type": "assignment_type",
                        "name": "homework"
                    }
                ]
            }
        }
    ]
}
*/

Update and re-score Item

For a specified target Item in one or more saved sessions, this endpoint updates those session(s) to use the latest Question validation rules from the Item bank, and rescores that Item in the existing sessions using the newly updated content.

The target_item specifies which Item in the provided session_ids should be updated.

The copy_item value can point to an alternative version of the Item that has been updated with the intended scoring rules. If provided, the Question definitions of copy_item will be copied over to the session and used for scoring purposes. This does not rewrite the original Item references in the session, therefore:

• The session's updated scores will continue to be reported against target_item.
• The session's Item source metadata accessible via Data API will still refer to target_item.

If copy_item is omitted, it defaults to the current definition of target_item in the Item bank.

The endpoint validates that the provided Item(s) and session(s) are compatible for rescoring. Specifically:

• the target_item and copy_item must contain the same number of Questions.
• the target_item and copy_item must contain identical Question types, in the same order.
• Each provided session_id must be in Completed status.

Note: If any of the given session_ids do not contain the target_item, they will be ignored during job processing.

If any validation errors occur at this stage, the endpoint will return a descriptive message and the sessions will not be modified.

If the validation is successful, the endpoint returns a job_reference. The status of the rescoring job can be retrieved by passing that job_reference to Data API's GET /jobs.

• The job may take up to 60 minutes to complete, depending on other load on Learnosity systems.
• Reviewing any of the given sessions while the rescoring job is in progress may cause inconsistent data to be displayed in the reviewed session.
• Resuming any of the given sessions while the rescoring job is in progress is not a supported use case and may cause errors in the session and/or the job.

Important: this endpoint has a rate limit of 1 request per 5 second window, per API consumer key.

For more details about this endpoint and the job resulting payload, see Rescoring: change or fix the autoscoring rules for an assessment.

Example

{
    "session_ids": [
        "f91a7773-c5b0-440a-86a4-b8f82c8a8119",
        "2761f570-c4ec-413d-ac9d-26e429e7f8df"
    ],
    "target_item": {
        "reference": "LRN-000045",
        "organisation_id": 32,
        "item_pool_id": "ipv1"
    },
    "copy_item": {
        "reference": "LRN-000046",
        "organisation_id": 32,
        "item_pool_id": "ipv2"
    }
}

/* Example Response:
{
    "meta":{
        "status":true
    },
    "data":{
        "job_reference": "9fd443d0-2b4f-4315-aec6-708da3d30d49"
    }
}
*/