Jobs
Methods for creating, monitoring, and managing job execution on the Istari Digital Platform.
All methods are available on the Client instance. Parameters marked (required) must be provided. See Enums for valid enum values and Pagination for page/size defaults.
Create and retrieve
add_job()
Add a new job to a model.
This method creates and registers a new job associated with the specified model. You can define the job’s function and optionally provide input parameters, execution environment details, and descriptive metadata.
-
Parameters:
- model_id (str) – Unique identifier of the model to which the job will be attached.
- function (str) – Name of the function that the job will execute.
- parameters (JSON | None) – Optional structured input parameters to pass to the function.
- parameters_file (PathLike | None) – Optional filesystem path to a file containing job parameters.
- tool_name (str | None) – Optional name of the tool used in this job.
- tool_version (str | None) – Optional version of the tool used in this job.
- operating_system (OS | None) – Optional target operating system for job execution. See OS for valid values (e.g.
Windows 11,Ubuntu 24.04). - assigned_agent_id (str | None) – Optional ID of a specific agent to execute the job.
- assigned_agent_pool_id (str | None) – Optional ID of an agent pool to execute the job.
- agent_id (str | None) – Optional identifier for the agent that created the job.
- sources (list [**NewSource | str ] | None) – Optional list of sources associated with the job. Each item may be a NewSource instance or a string source name.
- description (str | None) – Optional description of the job.
- version_name (str | None) – Optional user-defined version label for the job.
- external_identifier (str | None) – Optional external system identifier for the job.
- display_name (str | None) – Optional human-readable name for the job.
-
Return Type: Job
get_job()
Gets a job by id.
-
Parameters:
- job_id (str) – The id of the job to get. (required)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: Job
update_job()
Update an existing job with a new file and optional metadata.
This method replaces the contents of a job by uploading a new file and allows updating associated metadata such as description, version name, external identifier, and sources.
-
Parameters:
- job_id (str) – Unique identifier of the job to update.
- path (PathLike) – Filesystem path to the new job file.
- sources (list [**NewSource | str ] | None) – Optional list of sources associated with the job. Each item may be a NewSource instance or a string source name.
- description (str | None) – Optional updated description of the job.
- version_name (str | None) – Optional user-defined version label for the job.
- external_identifier (str | None) – Optional external system identifier for the job.
- display_name (str | None) – Optional human-readable name for the job.
-
Return Type: Job
List and filter
list_jobs()
Lists the jobs that a user has access to.
-
Parameters:
- model_id (str) – Filter jobs by model id
- status_name (JobStatusName) – Filter jobs by status name. One of:
Created,Pending,Claimed,Validating,Running,Uploading,Completed,Failed,Canceled,Unknown. - all_users (bool) – Show jobs owned by all users (requires admin privileges).
- page (int) – Page number. Min:
1. Default:1. - size (int) – Page size. Range:
0–100. Default:10. - archive_status (ArchiveStatus) – Filter jobs by archive status. One of:
active,archived,all. Default:active. - sort (str)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: PageJob
list_model_jobs()
Lists all jobs a user has access to for a model.
-
Parameters:
- model_id (str) – The id of the model to list jobs for. (required)
- status_name (JobStatusName) – Filter results by job status. One of:
Created,Pending,Claimed,Validating,Running,Uploading,Completed,Failed,Canceled,Unknown. - page (int) – Page number. Min:
1. Default:1. - size (int) – Page size. Range:
0–100. Default:10. - archive_status (ArchiveStatus) – Filter results by archive status. One of:
active,archived,all. Default:active. - sort (str)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: PageJob
Status and assignment
update_job_status()
Updates the status of a job.
-
Parameters:
- job_id (str) – The id of the job to update (required)
- status_name (JobStatusName) – The new status name to update the job with. One of:
Created,Pending,Claimed,Validating,Running,Uploading,Completed,Failed,Canceled,Unknown. (required) - agent_id (str) – An optional id for the agent.
- job_status_message (JobStatusMessage)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: Job
update_job_assigned_agent()
Updates the assigned agent for a job.
-
Parameters:
- job_id (str) – The id of the job to update the assigned agent for. (required)
- new_job_assigned_agent (NewJobAssignedAgent) – (required)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: Job
remove_job_assigned_agent()
Removes the assigned agent from a job.
-
Parameters:
- job_id (str) – The id of the job to remove the assigned agent from. (required)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: Job
Archive and restore
archive_job()
Archives a job by updating it’s archive status to Archived.
-
Parameters:
- job_id (str) – The id of the job to archive. (required)
- archive (Archive)
- http_request_timeout_secs (int , optional) – timeout setting for this request
-
Return Type: Job
restore_job()
Restores a job by updating it’s archive status to Active.