Jobs Endpoints

The jobs endpoints are for creating long running Learnosity jobs and checking their status and output.

You would want to use this for endpoints that run large processing jobs that may take some time (potentially hours) to return. Jobs can be queried to check on the progress periodically and allow you to retrieve the results once ready.

Usage

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

https://data.learnosity.com/[LTS_VERSION]/jobs

For example, to use the 2023.3.LTS version and the 'Get Jobs' endpoint, you would create a request like so:

https://data.learnosity.com/v2023.3.LTS/jobs

The following endpoints are available:

• Get Jobs
• Calculate Subscores Job
• Commence Dataset Job
• Change Sessions Statuses and Trigger Followup Processing
• Change Sessions Metadata

Get Jobs

Returns information about any job that has previously been started.

Example

{
    "references": [
        "9fd443d0-2b4f-4315-aec6-708da3d30d49"
    ]
}

/* Example Response:
{
    "meta":{
        "status":true,
        "timestamp":1389192595
        "records": 1
    },
    "data": [
        {
            "reference": "9fd443d0-2b4f-4315-aec6-708da3d30d49",
            "type": "manualresponseupdate",
            "status": "completed",
            "dt_created": "2015-04-24 01:30:02",
            "dt_completed": "2015-04-24 01:30:03"
        }
    ]
}
*/

Calculate Subscores Job

Generates subscore information on sessions. Subscores are a breakdown of a total score achieved for an Activity.

You would want to use this to extract groups of Items, and focus on scoring them separately. See Using Subscores With Your Activities for more information.

Note: only returns data if the subscore information was available at the time the learner attempted the session.

Example

{
    "session_id": [
        "8fac2b77-ebcb-42f6-a9cf-796467e8369a",
        "ea534769-d42f-404b-84eb-819023dabd05",
        "a9d6e989-c2cf-47c5-803a-c47fe49529e4",
        "f0a8b3aa-7c18-4f66-b6f6-66d99ef440d4"
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1437958049,
        "records": 2
    },
    "data": {
        "job_reference": "6b201463-5a2b-4d75-b689-12a1bb42ac50",
        "ignored_sessions": [
            "8fac2b77-ebcb-42f6-a9cf-796467e8369a"
        ]
    }
}
*/

Commence Dataset Job

Queues a job to compile the dataset specified in the request.

Before queueing the job, the provided dataset parameters are validated to ensure the dataset is ready to be processed. When the validation is successful, the endpoint returns a job_reference. Use the GET /jobs endpoint to poll the progress of the job.

Example

{
    "dataset_type": "activity-summary-by-group",
    "dataset_id": "e63de7cf-8a11-4b87-9a98-aba1af4e5340"
}

/* Example response:
{
    "meta": {
        "status": true,
        "timestamp": 1474336936
    },
    "data": {
        "job_reference": "402ead85-5a27-4d40-b68b-7b1e77924ed4",
        "dataset_type": "activity-summary-by-group",
        "dataset_id": "e63de7cf-8a11-4b87-9a98-aba1af4e5340"
    }
}
*/

Change Sessions Statuses and Trigger Followup Processing

Update the status of the given sessions.

If the requested status is "Completed", followup processing tasks will also be scheduled, such as:

• rescoring - based on historical data of the Questions/Items when sessions were initially taken by learners,
• subscore calculations,
• data API push events for the firehose service, and/or
• reports generation for Data API's sessions, reports, and adaptive.

Example

{
    "statuses": [
    {
      "user_id": "ANONYMIZED_USER_01",
      "session_id": "7939ead7-3242-4907-850d-3e5e48130277",
      "status": "Completed"
    },
    {
      "user_id": "ANONYMIZED_USER_02",
      "session_id": "5a74a4e9-6b6b-42a2-885e-127b795ba70c",
      "status": "Incomplete"
    }
    ]
}

/* Example 200 OK Response:
{
    "meta": {
        "status": true,
        "timestamp": 1487049275
    },
    "data": {
        "job_reference": "8a3d0ca2-eaa4-4c18-b9b9-1b12164e8b4e"
    }
}
*/

Change Sessions Metadata

Update the metadata of the given sessions. You can add your own additional custom information related to sessions or apply session Tags.

Example

{
    "session_metadata": [
        {
            "user_id": "e2c1ae85-bc62-4b70-ada2-fd8cb3949644",
            "session_id": "9ce7daeb-e117-4d14-9452-c94a0afe203b",
            "metadata": {
                "session_tags": [
                    {
                        "type": "assignment_type",
                        "name": "homework"
                    }
                ]
            }
        }
    ]
}

/* Example 200 OK Response:
{
    "meta": {
        "status": true,
        "timestamp": 1487049275
    },
    "data": {
        "job_reference": "8a3d0ca2-eaa4-4c18-b9b9-1b12164e8b4e"
    }
}
*/