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.

Returns user responses and scores per session.

Endpoint v1/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.
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.

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.

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.

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",
      "course_id": "example_course_id",
      "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 v1/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.

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.

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,
      "course_id": "chemistry",
      "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,
      "course_id": "economics",
      "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 v1/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.

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.

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,
      "course_id": "chemistry",
      "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 v1/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 v1/jobs/sessions/statuses endpoint.

Endpoint v1/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.

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.

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.

Endpoint v1/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.

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.

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",
      "course_id": "example_course_id",
      "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 v1/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
string

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 v1/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, 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 v1/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 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 v1/jobs/sessions/metadata endpoint.

Endpoint v1/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.

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.

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