Sessions Endpoints

The Data API's session endpoints allow you to programmatically retrieve and operate on the raw assessment data of your users. These endpoints are useful for data warehousing and for specialised reporting on the content, status and scoring of user 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.1.LTS version and the 'Responses' sessions endpoint, you would create a request like so:

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

Returns user responses and scores per session.

Endpoint /sessions/responses
HTTP Method POST
Action Type get
Notes The dt_score_updated field returned with each response object reflects the time of the most recent update to the response record, resulting from a save, submit, auto scoring or manual scoring operation.
This field will be updated only if there is an actual change in score value of related response object.
Parameter Description
activity_id
array

Array of Strings. Up to 1000 ids may be provided.
include
object

Object of additional keys to include in the response. Currently supports sessions.session_metadata.
include["sessions.session_metadata"]
array

Array of Strings. Specifies which fields of previously stored session metadata should be included in the response. Only existing fields are returned.

Example

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

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the sessions updated time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
maxtime_started
int | string

A timestamp filter based on the sessions start time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
maxtime_completed
int | string

A timestamp filter based on the sessions submit time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
mintime
int | string

A timestamp filter based on the sessions updated time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
mintime_started
int | string

A timestamp filter based on the sessions start time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
mintime_completed
int | string

A timestamp filter based on the sessions submit time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
next
string

A string token used to request the next page of results. The return packet will always include a string token in meta.next as resultset might have more records in the future. Pass the token along with the original request parameters to retrieve the next page of results.
session_id
array

Array of Strings. Up to 1000 ids may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
status
array

Array of Strings. Filters resultset to sessions in any of the specified statuses. If omitted, results are not filtered by session status. Valid statuses are:

  • Incomplete
  • Completed
  • Discarded
  • Pending Scoring
user_id
array

Array of Strings. 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": 4,
      "status": "Completed",
      "dt_started": "2014-03-04T02:53:35Z",
      "dt_completed": "2014-03-04T02:57:15Z",
      "responses": [
        {
            "response_id": "340BF0ED-77B0-45D0-A81EBE2F69DB51C1_sbalancedtestg3q1",
            "question_type": "imageclozeassociation",
            "dt_score_updated": "2017-06-19T02:03:19Z",
            "automarkable": false,
            "response": null
        },
        {
            "response_id":"DC03CFD5-D56D-4B2C-962D0926D0046B9D_sb3q12_1",
            "question_type":"longtextV2",
            "dt_score_updated": "2017-06-19T02:03:19Z",
            "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"
        }
      ]
    }
  ]
}
*/

Note on session_duration

session_duration is the time, in minutes rounded up, between when the session is started, dt_started, and when the session is completed,dt_completed.
time is measured in seconds. The time starts when you navigate to an Item, and it stops when you navigate away from it. Pausing the Activity will also stop the time. Moving to a different tab in the browser does not affect it. The time will continue to add up even though the tab is inactive.
If the session is saved, and then later resumed, the session_duration will include the number of minutes it was saved for. To calculate the time spent on a session, ignoring when it was saved, total the time spent on each Item. In the above example the total time spent is 85 + 65 + 70 = 220 seconds.
As this session was not saved and resumed we see that 220 seconds = 3.67 minutes which rounds up to 4 minutes.

Returns user scores per session, no responses.

Endpoint /sessions/scores
HTTP Method POST
Action Type get
Parameter Description
activity_id
array

Array of Strings. Up to 1000 ids may be provided.
include_response_scores
boolean

Whether to include the responses object (and scores per response).

Default: false
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the sessions updated time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
maxtime_started
int | string

A timestamp filter based on the session’s start time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
maxtime_completed
int | string

A timestamp filter based on the session’s submit time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
mintime
int | string

A timestamp filter based on the sessions updated time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
mintime_started
int | string

A timestamp filter based on the session’s start time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
mintime_completed
int | string

A timestamp filter based on the session’s submit time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
session_id
array

Array of Strings. Up to 1000 ids may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
status
array

Array of Strings. Filters resultset to sessions in any of the specified statuses. If omitted, results are not filtered by session status. Valid statuses are:

  • Incomplete
  • Completed
  • Discarded
  • Pending Scoring
user_id
array

Array of Strings. 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"
    }
  ]
}
*/

Returns user responses and scores per session, no Item information (as you get with sessions/responses).

Endpoint /sessions/responses/scores
HTTP Method POST
Action Type get
Notes The dt_score_updated field returned with each response object reflects the time of the most recent update to the response record, resulting from a save, submit, auto scoring or manual scoring operation.
Parameter Description
activity_id
array

Array of Strings. Up to 1000 ids may be provided.
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the sessions updated time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
maxtime_started
int | string

A timestamp filter based on the sessions start time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
maxtime_completed
int | string

A timestamp filter based on the sessions submit time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
mintime
int | string

A timestamp filter based on the sessions updated time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
mintime_started
int | string

A timestamp filter based on the sessions start time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
mintime_completed
int | string

A timestamp filter based on the sessions submit time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
session_id
array

Array of Strings. Up to 1000 ids may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
status
array

Array of Strings. Filters resultset to sessions in any of the specified statuses. If omitted, results are not filtered by session status. Valid statuses are:

  • Incomplete
  • Completed
  • Discarded
  • Pending Scoring
user_id
array

Array of Strings. 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"
        },
        {...}
    }
  ]
}
*/

Updates individual response scores within a single session.

Endpoint /sessions/responses/scores
HTTP Method POST
Action Type update
Parameter Description
sessions
array

Array of session objects. Limited to 1000 entries.
sessions[].session_id
string

The id of the session.
sessions[].user_id
string

The id of the user for the session.
sessions[].responses
array

Array of responses to update for the session.
sessions[].responses[].response_id
string

The response id
sessions[].responses[].score
float

The new score for this response.
sessions[].responses[].max_score
float

Optional new max score for this response.
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

Optional manual portion of the score.
sessions[].responses[].max_manual_score
float

Optional manual portion of the max score.

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"
    }
}
*/

Returns information about a session, when it was started, is it completed, now many questions were attempted etc.

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

Endpoint /sessions/statuses
HTTP Method POST
Action Type get
Parameter Description
activity_id
array

Array of Strings. Up to 1000 ids may be provided.
include
object

Object of additional keys to include in the sessions. Currently supports sessions.
include.sessions
array

Array of Strings. Specifies which additional fields should be included in the response. Only existing fields are returned.

Currently supports activity_template_id.
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the sessions updated time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
maxtime_started
int | string

A timestamp filter based on the sessions start time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
maxtime_completed
int | string

A timestamp filter based on the sessions submit time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
mintime
int | string

A timestamp filter based on the sessions updated time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
mintime_started
int | string

A timestamp filter based on the sessions start time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
mintime_completed
int | string

A timestamp filter based on the sessions submit time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
session_id
array

Array of Strings. Up to 1000 ids may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
status
array

Array of Strings. Filters resultset to sessions in any of the specified statuses. If omitted, results are not filtered by session status. Valid statuses are:

  • Incomplete
  • Completed
  • Discarded
  • Pending Scoring
user_id
array

Array of Strings. 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
        }
    ]
}
*/

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 (version added: v2020.2.LTS).

Endpoint /sessions/reports/adaptive
HTTP Method POST
Action Type get
Parameter Description
activity_id
array

Array of Strings. Up to 1000 ids may be provided.
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the sessions updated time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
maxtime_started
int | string

A timestamp filter based on the sessions start time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
maxtime_completed
int | string

A timestamp filter based on the sessions submit time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
mintime
int | string

A timestamp filter based on the sessions updated time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
mintime_started
int | string

A timestamp filter based on the sessions start time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
mintime_completed
int | string

A timestamp filter based on the sessions submit time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
session_id
array

Array of Strings. Up to 1000 ids may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
status
array

Array of Strings. Filters resultset to sessions in any of the specified statuses. If omitted, results are not filtered by session status. Valid statuses are:

  • Incomplete
  • Completed
  • Discarded
  • Pending Scoring
user_id
array

Array of Strings. 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"
          ]
        }
      }
    }
  ]
}
*/

This endpoint supports the programmatic creation of new sessions. Use the endpoint to obtain a JSON session template corresponding to Items or an Activity, then submit the template to Learnosity with one or more sets of student responses via the SET sessions endpoint (with the "data_format": "from_template" parameter).

This endpoint accepts requests formatted similarly to the Items API initialisation options. The following table lists the most relevant ones only. Note that user_id, activity_id and session_id are forbidden (these will be provided per session when calling SET sessions), as well as the adaptive object.

Endpoint /sessions/templates
HTTP Method POST
Action Type get
Parameter Description
items
array

Reference of Items to retrieve. Can either be strings, or objects; see the Items API initialisation options. Required except when activity_template_id is present, and that Activity template itself has Items.
activity_template_id
string

Reference of an Activity definition stored to use as a template.
item_pool_id
string

Specifies the Item pool from which to retrieve the items/activity template.
organisation_id
integer

Specifies the organisation from which to retrieve the items/activity template.
scoring_type
string

Overrides the scoring type of the Items loaded from the Item bank; see the Items API initialisation options.
subscores
array

Subscore definition for the Activity; see the Items API initialisation options.

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": "Ox",
                        "value": "1"
                    },
                    {
                        "label": "Chicken",
                        "value": "2"
                    },
                    {
                        "label": "Kangaroo",
                        "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"
            }
        ]
    }
}
*/

Post failed submissions here to import them into the Learnosity platform.

Endpoint /sessions
HTTP Method POST
Action Type set
Parameter Description
data
array

Array of strings. Limited to 50 entries.
data_format
string

Which format you are sending the request payload in. Values must be either:

Default: failed_submission
ignore_response_revisions
boolean

Questions API stores a revision number for each response in a session. This number is incremented each time the user changes the response. When a response is saved, if its revision number is less than one saved previously, the save fails. This behaviour also applies to the responses you send to this endpoint. This helps prevent data loss where newer responses have already been saved for a session e.g. a student may have provided you with a failed submission packet, before later resuming their session and saving new responses.

ignore_response_revisions allows you to disable this behaviour. When set to true, all responses in your failed submission data will be saved, regardless of the revision numbers on any existing saved responses in Questions API.

Default: false

Example

{
    "data_format": "failed_submission",
    "data": [
        "[BASE64 ENCODED SESSION HASH]",
        "[BASE64 ENCODED SESSION HASH]",
        "[BASE64 ENCODED SESSION HASH]",
        "[BASE64 ENCODED SESSION HASH]"
    ]
}

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

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

The endpoint will create a job to be completed asynchronously. Poll the GET jobs endpoint using 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 . Please contact Learnosity support if you want to use others question types not listed above.

Endpoint /sessions
HTTP Method POST
Action Type set
Parameter Description
data_format
string

Must be the value "from_template".
template
object

Object retrieved from the GET sessions/templates endpoint.
data
array [objects]

List of sessions and responses to create programmatically against the given template. Limited to 50 entries.
ignore_response_revisions
boolean

Questions API stores a revision number for each response in a session. This number is incremented each time the user changes the response. When a response is saved, if its revision number is less than one saved previously, the save fails. This behaviour also applies to the responses you send to this endpoint. This helps prevent data loss when newer responses have already been saved for a session.

ignore_response_revisions allows you to disable this behaviour. When set to true, all responses sent to this endpoint will be saved, regardless of the revision numbers on any existing saved responses in Questions API.

Default: false
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 question_id field is common.
data.[].responses.[].question_id
string

Identifier of the question that this response is for; must match one of the question.id values in the template object.
Response packet for association, clozeinlinetext and clozetext
data.[].responses.[].type
string

Must be the value "array".
data.[].responses.[].value
array [string]

Array of one or more strings representing the response(s) that should be recorded for this question.

Each string value must match one of the possible options from the template.questions.[].options (or stimulus_list for association) array for the question denoted by question_id. Unanswered questions are marked with a null value.
Response packet for choicematrix
data.[].responses.[].type
string

Must be the value "array".
data.[].responses.[].value
array [array [integer]]

Array of arrays of one or more integer representing the response(s) that should be recorded for each of the sub-questions.
Response packet for clozeformula
data.[].responses.[].type
string

Must be the value "array".
data.[].responses.[].responses
array [array [string]]

Array of arrays of the responses that the student provided into each individual response box.
data.[].responses.[].value
array [array [string]]

Array of arrays of one or more full formulas built based on the student's responses. These formulas are the scoreable answers
Response packet for formulaV2
data.[].responses.[].type
string

Must be the value "string".
data.[].responses.[].value
string

The response string (URL-encoded, with + instead of spaces).
Response packet for gridded
data.[].responses.[].type
string

Must be the value "string".
data.[].responses.[].value
string

A string representing the number entered, including . as the decimal point, if relevant.
Response packet for longtext, longtextV2 and plaintext
data.[].responses.[].type
string

Must be the value "string".
data.[].responses.[].value
string

The response string (URL-encoded, with + instead of spaces).
data.[].responses.[].wordCount
integer

The number of words in value.
Response packet for mcq
data.[].responses.[].type
string

Must be the value "array".
data.[].responses.[].value
array [string]

Array of one or more strings representing the response(s) that should be recorded for this question.

Each string value must match one of the possible options from the template.questions.[].options.
Response packet for orderlist
data.[].responses.[].type
string

Must be the value "array".
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 data.list array. For example, if data.list=['a', 'b', 'c', 'd'] and the user chose the order d, b, a, c, the response array will contain [3, 2, 4, 1].
Response packet for shorttext
data.[].responses.[].type
string

Must be the value "string".
data.[].responses.[].value
string

The response string (URL-encoded, with + instead of spaces).
data.[].responses.[].characterCount
integer

The number of characters in value.

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"
    }
}
*/

Return metadata associated with the session.

Note: session metadata can be updated with the SET /jobs/sessions/metadata endpoint.

Endpoint /sessions/metadata
HTTP Method POST
Action Type get
Notes The dt_score_updated field returned with each response object reflects the time of the most recent update to the response record, resulting from a save, submit, auto scoring or manual scoring operation.
Parameter Description
activity_id
array

Array of Strings. Up to 1000 ids may be provided.
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the sessions updated time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
maxtime_started
int | string

A timestamp filter based on the sessions start time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
maxtime_completed
int | string

A timestamp filter based on the sessions submit time. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.

(version added: v2023.3.LTS)
mintime
int | string

A timestamp filter based on the sessions updated time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
mintime_started
int | string

A timestamp filter based on the sessions start time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
mintime_completed
int | string

A timestamp filter based on the sessions submit time. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.

(version added: v2023.3.LTS)
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
session_id
array

Array of Strings. Up to 1000 ids may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
status
array

Array of Strings. Filters resultset to sessions in any of the specified statuses. If omitted, results are not filtered by session status. Valid statuses are:

  • Incomplete
  • Completed
  • Discarded
  • Pending Scoring
user_id
array

Array of Strings. 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"
                    }
                ]
            }
        }
    ]
}
*/

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[1] that Item in the sessions using the newly updated content.

The session_ids array may contain up to 100 session_id strings.

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

copy_item 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:

  • target_item and copy_item must contain the same number of Questions.
  • 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.

Note that this endpoint currently has a rate limit of 1 request per 5 second window, per consumer key.

For more details about this feature and the job result payload, see our knowledge base article on rescoring.

1. Note: rescoring for Items containing dynamic content and simple Features is a newer capability. Version added: v2020.3.LTS.

Endpoint /sessions/item
HTTP Method POST
Action Type update
Parameter Description
session_ids
array [string]

Array of session id strings. Limited to 100 entries.
target_item
object

An Item reference object describing the selected Item to be updated in the sessions.
target_item.reference
string

The reference of the "target" Item.
target_item.organisation_id
integer

Optional; the id of the Item bank from which to retrieve the "target" Item. Defaults to the primary Item bank of the consumer if unspecified.
target_item.item_pool_id
string

Optional; the Item pool from which to retrieve the "target" Item. Uses the Item bank if unspecified.
copy_item
object

An optional Item reference object describing a specific Item to use as the source of updated Question validation rules.

If a "copy" Item is not specified, then the "target" Item is used as the source.
copy_item.reference
string

The reference of the "copy" Item.
copy_item.organisation_id
integer

Optional; the id of the Item bank from which to retrieve the "copy" Item. Defaults to the primary Item bank of the consumer if unspecified.
copy_item.item_pool_id
string

Optional; the Item pool from which to retrieve the "copy" Item. Uses the Item bank if unspecified.

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"
    }
}
*/