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
The following endpoints are available:
Responses
Returns learner responses and scores per session.
Notes- 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 inscore
value.
Endpoint | /[LTS_VERSION]/sessions/responses |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
activity_id array[string] |
A list of Activity IDs. Up to 1000 IDs may be provided. |
include object |
Additional keys to include in the response. See below for supported keys. |
include["sessions.session_metadata"] array[string] |
Specifies which attributes of previously stored session metadata should be included in the response. Only existing attributes are returned. Example:
|
limit integer |
Restricts the number of records returned, with a maximum of 50. Default: 50 |
maxtime integer | string |
A timestamp filter based on the session's updated time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. |
maxtime_started integer | string |
A timestamp filter based on the session's start time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
maxtime_completed integer | string |
A timestamp filter based on the session's submission time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
mintime integer | string |
A timestamp filter based on the session's updated time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. |
mintime_started integer | string |
A timestamp filter based on the session's start time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
mintime_completed integer | string |
A timestamp filter based on the session's submission time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
session_id array[string] |
A list of session IDs to retrieve. Up to 1000 IDs may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
status array[string] |
Filters the result set to retrieve sessions containing any of the specified statuses. Possible values:
|
user_id array[string] |
A list of user IDs to include. Up to 1000 IDs may be provided. |
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.
Endpoint | /[LTS_VERSION]/sessions/scores |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
activity_id array[string] |
A list of Activity IDs to include. Up to 1000 IDs may be provided. |
include_response_scores boolean |
Controls whether to include the response object and scores per response. Default: |
limit integer |
Restricts the number of records returned, with a maximum of 50. Default: 50 |
maxtime integer | string |
A timestamp filter based on the session's updated time. Latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. |
maxtime_started integer | string |
A timestamp filter based on the session's start time. Latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
maxtime_completed integer | string |
A timestamp filter based on the session's submission time. Latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
mintime integer | string |
A timestamp filter based on the session's updated time. Earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. |
mintime_started integer | string |
A timestamp filter based on the session's start time. Earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
mintime_completed integer | string |
A timestamp filter based on the session's submission time. Earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
session_id array[string] |
A list of sessions IDs to include. Up to 1000 IDs may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
status array[string] |
Filters the result set to retrieve sessions containing any of the specified statuses. Possible values:
|
user_id array[string] |
A list of user IDs to include. Up to 1000 IDs may be provided. |
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 inscore
value.
Endpoint | /[LTS_VERSION]/sessions/responses/scores |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
activity_id array[string] |
A list of Activity IDs. Up to 1000 IDs may be provided. |
limit integer |
Restricts the number of records returned, with a maximum of 50. Default: 50 |
maxtime integer | string |
A timestamp filter based on the session's updated time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. |
maxtime_started integer | string |
A timestamp filter based on the session's start time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
maxtime_completed integer | string |
A timestamp filter based on the session's submission time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
mintime integer | string |
A timestamp filter based on the session's updated time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. |
mintime_started integer | string |
A timestamp filter based on the session's start time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
mintime_completed integer | string |
A timestamp filter based on the session's submission time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
session_id array[string] |
A list of session IDs to retrieve. Up to 1000 IDs may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
status array[string] |
Filters the result set to retrieve sessions containing any of the specified statuses. Possible values:
|
user_id array[string] |
A list of user IDs to include. Up to 1000 IDs may be provided. |
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.
Endpoint | /[LTS_VERSION]/sessions/responses/scores |
---|---|
HTTP Method | POST |
Action Type | update |
Parameter | Description |
sessions array[objects] |
List of sessions to be updated. Maximum 1000 entries. See below for session object attributes. |
sessions[].session_id string |
The ID of the session. |
sessions[].user_id string |
The ID of the user (learner) for the session. |
sessions[].responses array[object] |
Responses to update for the session. See below for response object attributes. |
sessions[].responses[].response_id string |
The response ID. |
sessions[].responses[].score float |
The updated score for this response. |
sessions[].responses[].max_score float |
The updated maximum score for this response. (Optional) |
sessions[].responses[].attempted boolean |
Attempted status of the response. When setting a non-zero score, the response must also be attempted. |
sessions[].responses[].manual_score float |
The value of the manual score for the response, usually given by the educator. (Optional) |
sessions[].responses[].max_manual_score float |
The value of the maximum manual score that can be given. (Optional) |
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.
Endpoint | /[LTS_VERSION]/sessions/statuses |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
activity_id array[string] |
A list of Activity IDs. Up to 1000 IDs may be provided. |
include object |
Additional keys to include in the response. See below for supported keys. |
include.sessions array[string] |
Specifies which additional fields should be included in the response. Only existing fields are returned. The value must be Example:
|
limit integer |
Restricts the number of records returned, with a maximum of 50. Default: 50 |
maxtime integer | string |
A timestamp filter based on the session's updated time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. |
maxtime_started integer | string |
A timestamp filter based on the session's start time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
maxtime_completed integer | string |
A timestamp filter based on the session's submission time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
mintime integer | string |
A timestamp filter based on the session's updated time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. |
mintime_started integer | string |
A timestamp filter based on the session's start time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
mintime_completed integer | string |
A timestamp filter based on the session's submission time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
session_id array[string] |
A list of session IDs to retrieve. Up to 1000 IDs may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
status array[string] |
Filters the result set to retrieve sessions containing any of the specified statuses. Possible values:
|
user_id array[string] |
A list of user IDs to include. Up to 1000 IDs may be provided. |
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.
Endpoint | /[LTS_VERSION]/sessions/reports/adaptive |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
activity_id array[string] |
A list of Activity IDs. Up to 1000 IDs may be provided. |
limit integer |
Restricts the number of records returned, with a maximum of 50. Default: 50 |
maxtime integer | string |
A timestamp filter based on the session's updated time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. |
maxtime_started integer | string |
A timestamp filter based on the session's start time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
maxtime_completed integer | string |
A timestamp filter based on the session's submission time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
mintime integer | string |
A timestamp filter based on the session's updated time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. |
mintime_started integer | string |
A timestamp filter based on the session's start time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
mintime_completed integer | string |
A timestamp filter based on the session's submission time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
session_id array[string] |
A list of session IDs to retrieve. Up to 1000 IDs may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
status array[string] |
Filters the result set to retrieve sessions containing any of the specified statuses. Possible values:
|
user_id array[string] |
A list of user IDs to include. Up to 1000 IDs may be provided. |
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.
Endpoint | /[LTS_VERSION]/sessions/templates |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
items array[string|object] |
A list of Item references to add to the session template. Can either be strings or objects. See the Items API initialization option for more information. Required except when |
activity_template_id string |
The Activity containing Items you want to use as a template for the session. See the Items API initialization option for more information. |
item_pool_id string |
Specifies the Item pool from which to retrieve the Items or Activity template. See the Items API initialization option for more information. |
organisation_id integer |
Specifies the Item bank from which to retrieve the Items or Activity template. See the Items API initialization option for more information. |
scoring_type string |
Overrides the scoring type of the Items loaded from the Item bank. See the Items API initialization option for more information. |
subscores array |
Subscore definition for the Activity See the Items API initialization option for more information. |
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.
Endpoint | /[LTS_VERSION]/sessions |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
data array[string] |
An array of base64 strings that represent the learner's session data. See Configuring Behavior in Case of Network Failure & Failed Submission for more information on how a learner can obtain their session data. Maximum: 50 entries. |
data_format string |
The format of the request payload. Must be |
ignore_response_revisions boolean |
Ignores the revision value inside a recorded response. See Understanding Submission and Scoring for more information. Default: |
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.
Endpoint | /[LTS_VERSION]/sessions |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
data_format string |
Must be |
template object |
Session template retrieved from the |
ignore_response_revisions boolean |
Ignores the revision value inside a recorded response. See Understanding Submission and Scoring for more information. Default: |
data array[objects] |
A list of sessions and responses to create programmatically against the given Maximum 50 entries. See below for data object attributes. |
data.[].user_id string |
Identifier for the user. |
data.[].activity_id string |
Identifier for the Activity. |
data.[].session_id string (UUID) |
Identifier for the session. |
data.[].responses array [object] |
List of responses corresponding to the set of questions contained in the template. The format of the object varies with the Question type, but the |
data.[].responses.[].question_id string |
Identifier of the question that this response is for; must match one of the |
Response packet for association , clozeinlinetext , and clozetext
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value array[string] |
The responses that should be recorded for this Question. Array of one or more strings. Each string value must match one of the possible options as defined in the Question. To create an unattempted Question, set the value to |
Response packet for choicematrix |
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value array[array[integer]] |
The responses that should be recorded for this Question. Array of arrays of one or more integers representing the response(s) that should be recorded for each of the sub-questions. See example for more information. |
Response packet for clozeformula |
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].responses array[array[string]] |
The responses that should be recorded for this Question. Array of arrays of the responses that is provided for each individual response box. |
data.[].responses.[].value array[array[string]] |
Array of arrays of one or more full formulas built based on the learner's responses. These formulas are the scoreable answers. |
Response packet for formulaV2
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value string |
The response string which is URL-encoded. Note: use |
Response packet for gridded
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value string |
A string representing the number entered, including |
Response packet for longtext , longtextV2 and plaintext
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value string |
The response string which is URL-encoded. Note: use |
data.[].responses.[].wordCount integer |
The word count from |
Response packet for mcq
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value array [string] |
The responses that should be recorded for this Question. Array of one or more strings. Each string value must match one of the possible options as defined in the Question. |
Response packet for orderlist
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value array[integer] |
Array of one or more integers representing the selected position of the response. The array should be in the original order as the For example, if |
Response packet for shorttext
|
|
data.[].responses.[].type string |
The data type value. Must be |
data.[].responses.[].value string |
The response string which is URL-encoded. Note: use |
data.[].responses.[].characterCount integer |
The character count from |
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.
Notes- 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 inscore
value.
Endpoint | /[LTS_VERSION]/sessions/metadata |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
activity_id array[string] |
A list of Activity IDs. Up to 1000 IDs may be provided. |
limit integer |
Restricts the number of records returned, with a maximum of 50. Default: 50 |
maxtime integer | string |
A timestamp filter based on the session's updated time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. |
maxtime_started integer | string |
A timestamp filter based on the session's start time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
maxtime_completed integer | string |
A timestamp filter based on the session's submission time. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. (version added: v2023.3.LTS) |
mintime integer | string |
A timestamp filter based on the session's updated time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. |
mintime_started integer | string |
A timestamp filter based on the session's start time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
mintime_completed integer | string |
A timestamp filter based on the session's submission time. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. (version added: v2023.3.LTS) |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
session_id array[string] |
A list of session IDs to retrieve. Up to 1000 IDs may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
status array[string] |
Filters the result set to retrieve sessions containing any of the specified statuses. Possible values:
|
user_id array[string] |
A list of user IDs to include. Up to 1000 IDs may be provided. |
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
andcopy_item
must contain the same number of Questions. - the
target_item
andcopy_item
must contain identical Question types, in the same order. - Each provided
session_id
must be inCompleted
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.
Endpoint | /[LTS_VERSION]/sessions/item |
---|---|
HTTP Method | POST |
Action Type | update |
Parameter | Description |
session_ids array[string] |
A list of session IDs. Up to 100 IDs may be provided. |
target_item object |
An Item reference object describing the selected Item to be updated in the sessions. See below for related attributes. |
target_item.reference string |
The reference of the "target" Item. |
target_item.organisation_id integer |
The ID of the Item bank from which to retrieve the "target" Item. Defaults to the primary Item bank of the API consumer if unspecified. (Optional) |
target_item.item_pool_id string |
The Item pool from which to retrieve the "target" Item. Uses the Item bank ( |
copy_item object |
An Item reference object describing a specific Item to use as the source of updated Question validation rules. (Optional) If a "copy" Item is not specified, then the "target" Item is used as the source. See below for related attributes. |
copy_item.reference string |
The reference of the "copy" Item. |
copy_item.organisation_id integer |
The ID of the Item bank from which to retrieve the "copy" Item. (Optional) Defaults to the primary Item bank of the API consumer if unspecified. |
copy_item.item_pool_id string |
The Item pool from which to retrieve the "copy" Item. Uses the Item bank if unspecified. (Optional) |
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"
}
}
*/