sessions-endpoints - Data API

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

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 in score 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:

{
    "include": {
        "sessions.session_metadata": ["my_existing_field"]
    }
}
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 limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

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:

  • "desc": descending
  • "asc": ascending

Default: "desc"

status
array[string]

Filters the result set to retrieve sessions containing any of the specified statuses.

Possible values:

  • "Incomplete"
  • "Completed"
  • "Discarded"
  • "Pending Scoring"
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.

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

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 limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

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:

  • "desc": descending
  • "asc": ascending

Default: "desc"

status
array[string]

Filters the result set to retrieve sessions containing any of the specified statuses.

Possible values:

  • "Incomplete"
  • "Completed"
  • "Discarded"
  • "Pending Scoring"
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"
        }
    ]
}
*/

Returns learner responses and scores per session without Item information. To include Item information, see the /sessions/responses 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 in score 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 limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

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:

  • "desc": descending
  • "asc": ascending

Default: "desc"

status
array[string]

Filters the result set to retrieve sessions containing any of the specified statuses.

Possible values:

  • "Incomplete"
  • "Completed"
  • "Discarded"
  • "Pending Scoring"
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"
            },
            {...}
        }
    ]
}
*/

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

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 ["activity_template_id"].

Example:

"include": {
"sessions": ["activity_template_id"]
}
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 limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

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:

  • "desc": descending
  • "asc": ascending

Default: "desc"

status
array[string]

Filters the result set to retrieve sessions containing any of the specified statuses.

Possible values:

  • "Incomplete"
  • "Completed"
  • "Discarded"
  • "Pending Scoring"
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
        }
    ]
}
*/

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 limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

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:

  • "desc": descending
  • "asc": ascending

Default: "desc"

status
array[string]

Filters the result set to retrieve sessions containing any of the specified statuses.

Possible values:

  • "Incomplete"
  • "Completed"
  • "Discarded"
  • "Pending Scoring"
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"
              ]
            }
          }
        }
    ]
}
*/

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

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

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

ignore_response_revisions
boolean

Ignores the revision value inside a recorded response.

See Understanding Submission and Scoring for more information.

Default: false

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

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

template
object

Session template retrieved from the GET /sessions/templates endpoint.

ignore_response_revisions
boolean

Ignores the revision value inside a recorded response.

See Understanding Submission and Scoring for more information.

Default: false

data
array[objects]

A list of sessions and responses to create programmatically against the given template.

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

The data type value. Must be "array".

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

Response packet for choicematrix
data.[].responses.[].type
string

The data type value. Must be "array".

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

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

data.[].responses.[].value
string

The response string which is URL-encoded.

Note: use + instead of spaces.

Response packet for gridded
data.[].responses.[].type
string

The data type value. Must be "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

The data type value. Must be "string".

data.[].responses.[].value
string

The response string which is URL-encoded.

Note: use + instead of spaces.

data.[].responses.[].wordCount
integer

The word count from value.

Response packet for mcq
data.[].responses.[].type
string

The data type value. Must be "array".

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 "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 learner chose the order: d, b, a, c, the response array will contain [3, 1, 0, 2].

Response packet for shorttext
data.[].responses.[].type
string

The data type value. Must be "string".

data.[].responses.[].value
string

The response string which is URL-encoded.

Note: use + instead of spaces.

data.[].responses.[].characterCount
integer

The character count from 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"
    }
}
*/

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 in score 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 limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

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:

  • "desc": descending
  • "asc": ascending

Default: "desc"

status
array[string]

Filters the result set to retrieve sessions containing any of the specified statuses.

Possible values:

  • "Incomplete"
  • "Completed"
  • "Discarded"
  • "Pending Scoring"
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"
                    }
                ]
            }
        }
    ]
}
*/

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.

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 (organisation_id) if unspecified. (Optional)

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"
    }
}
*/
Was this article helpful?

Did you arrive here by accident? If so, learn more about Learnosity.