Jobs Endpoints

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

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.1.LTS version and the 'Get Jobs' endpoint, you would create a request like so:

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

Returns information about any job that has previously been started.

Endpoint /jobs
HTTP Method POST
Action Type get
Parameter Description
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the created time of the job. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from.
mintime
int | string

A timestamp filter based on the created time of the job. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to.
organisation_id
integer

Returns only jobs filtered to the Item bank with the supplied ID.

The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console.
references
array

Array of Strings. Up to 1000 job references may be provided.
status
array

Array of strings, supports queued, running, halted and completed. Filters the resultset to jobs in any of the specified statuses.

Default: completed
include
array

Array of strings specifying additional properties to be included in the response. Supports data.

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

Generates subscore information on sessions, if subscore information was available at the time the student attempted the session.

Endpoint /jobs/sessions/scores/subscores
HTTP Method POST
Action Type get
Parameter Description
session_id
array

Array of String session_ids for which subscores should be recalculated. Up to 100 ids may be provided.

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

Queues a job to compile the dataset specified in the request. Before queueing the job, the provided dataset parameters and user/groups data are validated to ensure the dataset is ready to be compiled. If validation is successful, the endpoint returns a job_reference. Use the GET /jobs endpoint to poll the progress of the job.

Endpoint /jobs/reports/datasets
HTTP Method POST
Action Type set
Parameter Description
dataset_type
string

The type of dataset to begin generating.
dataset_id
string

Identifier of the dataset to begin generating.

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

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 students).
  • Subscore calculations
  • Data API push events
  • Reports generation for Data API's sessions/reports/adaptive
Endpoint /jobs/sessions/statuses
HTTP Method POST
Action Type update
Parameter Description
statuses
array

Array of session status objects representing the sessions to update. Up to 100 objects may be provided.
statuses[].session_id
string

The session_id to update.
statuses[].status
string

The status to apply to the session. Valid statuses are:

  • Completed
  • Incomplete
  • Discarded
statuses[].user_id
string

The user_id recorded against the session. Must match the user_id provided when the session was initialised.

Example

{
  "statuses": [
    {
      "user_id": "jessepinkman",
      "session_id": "7939ead7-3242-4907-850d-3e5e48130277",
      "status": "Completed"
    },
    {
      "user_id": "walterwhite",
      "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"
    }
}
*/

Update the metadata of the given sessions. Add arbitrary data or session tags.

Endpoint /jobs/sessions/metadata
HTTP Method POST
Action Type set
Parameter Description
session_metadata
array

Array of session metadata objects representing the sessions to update. Up to 100 objects may be provided.
session_metadata[].session_id
string

The session_id to update.
session_metadata[].metadata
object

The metadata to apply to the session. Existing metadata will be overwritten.
session_metadata[].user_id
string

The user_id recorded against the session. Must match the user_id provided when the session was initialised.

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