jobs-endpoints - Data API

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

Returns information about any job that has previously been started.

Endpoint /[LTS_VERSION]/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
integer | string

A timestamp filter based on the created time of the job. Latest UTC Unix timestamp or datetime string (in ISO 8601) to get results from.

mintime
integer | string

A timestamp filter based on the created time of the job. Earliest 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 API 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[string]

A list job references you want to retrieve.

Maximum: 1000 job references.

status
array[string]

Filters jobs containing any of the specified statuses.

Possible values:

  • "queued",
  • "running",
  • "halted" and
  • "completed".

Default: "completed"

include
array[string]

Restrict the properties returned in the data object.

Default: ["reference", "type", "status", "dt_created", "dt_completed"]

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

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

A list of session_ids for subscores that 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 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.

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

The type of dataset to begin generating.

Possible values:

  • "activity-summary-by-group",
  • "sessions-summary-by-group",
  • "ibk-analysis-by-question", or
  • "activity-analysis-by-question".
dataset_id
string

Identifier of the dataset to begin generating. This is provided when calling the reports/datasets endpoint.

See the datasets listed on Working With Datasets for more information.

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 learners,
  • subscore calculations,
  • data API push events for the firehose service, and/or
  • reports generation for Data API's sessions, reports, and adaptive.
Endpoint /[LTS_VERSION]/jobs/sessions/statuses
HTTP Method POST
Action Type update
Parameter Description
statuses
array[object]

Array of session status objects representing the sessions to update.

Up to 100 objects may be provided.

See below attributes for more information.

statuses[].session_id
string

The session ID to update.

statuses[].status
string

The status to apply to the session.

Possible values:

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

The user ID recorded against the session.

Must match the user_id provided when the session was initialized.

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

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

Endpoint /[LTS_VERSION]/jobs/sessions/metadata
HTTP Method POST
Action Type set
Parameter Description
session_metadata
array[object]

Array of session metadata objects representing the sessions to update.

Up to 100 objects may be provided.

See below attributes for more information.

session_metadata[].session_id
string

The session ID to update.

session_metadata[].metadata
object

The metadata to apply to the session. Any existing metadata will be overwritten.

session_metadata[].metadata.session_tags
array[TagsV2]

A list of session Tags to be applied to the session. See example below.

session_metadata[].user_id
string

The user ID recorded against the session.

Must match the user_id provided when the session was initialized.

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"
    }
}
*/
Was this article helpful?

Did you arrive here by accident? If so, learn more about Learnosity.