Response scores endpoint

Manage learner responses and scores per session without Item information.

Endpoints:

• Get Response Scores
• Update Response Scores

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/scores endpoint, you would create a request like so:

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

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.

Related articles:

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

Returns learner responses and scores per session without Item information. To include Item information, see the /sessions/responses endpoint.

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.

Request body parameters

Body content type: application/json

• activity_id array[string]

  A list of Activity IDs.

  Maximum entries: 1000

• 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

{
    "session_id": [
        "4d3115f0-1235-4613-5be6fc6e6b2e"
    ]
}

Responses

Response example

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

Request body parameters

Body content type: application/json

• sessions array[object]

  List of session object definitions for updating sessions.

  Maximum entries: 1000

  The following properties are supported.

  • session_id string

    The ID of the session.

  • user_id string

    The ID of the user (learner) for the session.

  • responses array[object]

    A list of response object definitions for updating the session responses.

    The following properties are supported.

    • response_id string

      The response ID.

    • score number (float)

      The updated score for this response.

    • max_score number (float)

      (Optional) The updated maximum score for this response.

    • attempted boolean

      Attempted status of the response. When setting a non-zero score, the response must also be attempted.

    • manual_score number (float)

      (Optional) The value of the manual score for the response, usually given by the educator.

    • max_manual_score number (float)

      (Optional) The value of the maximum manual score that can be given.

Request body 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
                }
            ]
        }
    ]
}

Responses

Response example

{
    "meta": {
        "status":true
    },
    "data": {
        "job_reference": "9fd443d0-2b4f-4315-aec6-708da3d30d49"
    }
}