Responses endpoint

Retrieve and operate on the raw assessment data of your learners.

Endpoints:

Get Responses

Usage

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

https://data.learnosity.com/{LTS_VERSION}/{endpoint}

For example, to use the v2025.2.LTS version and the /sessions/responses endpoint, you would create a request like so:

https://data.learnosity.com/v2025.2.LTS/sessions/responses

Important The Data API is not a REST API. All requests must use the POST method, with the action request body parameter specifying the operation to use. The Learnosity SDK must be used to make requests to Data API.

Note The Data API usage is subject to rate limits.

Getting Started with the Data API
See Release Cadence and Version Lifecycle for more information on available LTS versions.

Get Responses

Returns learner responses and scores per session.

Note 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"`

Request body parameters

Body content type: application/json

activity_id array[string]

A list of Activity IDs.

Maximum entries: 1000
include object

Additional keys to include in the response.

The following properties are supported.
- sessions.session_metadata array[string]
  
  Specifies which attributes of previously stored session metadata should be included in the response. Only existing attributes are returned.
```
{
    "include": {
        "sessions.session_metadata": ["my_existing_field"]
    }
}
```
limit integer

Restricts the number of records returned.

Default: 50

Maximum: 50
maxtime integer string

A timestamp filter based on the session's updated time. The latest UTC Unix timestamp or datetime string (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 (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 (ISO 8601) 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 (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 (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 (ISO 8601 format) to filter results to.

Version added: v2023.3.LTS
next string

Indicates the pagination token to be used for retrieving the next page of session data.

You would want to use this so that you can continue retrieving sessions or implement periodic polling to fetch new data over time.

The next token is included in responses from the sessions endpoint only when the current result set contains results, regardless of whether additional records exist beyond the current page. This enables you to implement long-polling strategies by reusing the last token in subsequent requests to detect newly created sessions.

Note This behavior differs from other Data API endpoints such as those under the Item bank, where the next token is only returned if more results exist beyond the current page.
session_id array[string]

A list of session IDs to retrieve.

Maximum length: 1000
sort string

Determines the response sorting by ascending or descending order.

Default: desc

Possible values
- asc
- desc
status array[string]

Retrieve only sessions that contain any of the specified statuses.

Possible values
- Incomplete
- Completed
- Discarded
- Pending Scoring
user_id array[string]

A list of user IDs to include.

Maximum length: 1000

Request body example

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

Responses

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.

Response example

{
    "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"
            }
        ]
    }]
}