Jobs¶
Overview¶
Job requests can be used to set and retrieve information for one or many jobs. Job requests support GET, PUT, POST and DELETE request types. For more about these request types and their uses see the Request Formats and Responses documentation.
Requests and Responses¶
List of possible requests for Jobs. All PUT and POST requests may also return a 400 Bad Request error if there was no message body in the request. All PUT requests may also return a 400 Bad Request error message if the command key is not present in the message body’s JSON object. All PUT requests may also return a 500 Internal Server Error error message if the command key in the message body contained an invalid command.
Get All The Jobs
URL: http://hostname:portnumber/api/jobs
Request Type: GET
Message Body: N/A
Response: JSON object containing all the job information for every job in the repository.
Possible Errors: 500 Internal Server Error: An exception occurred within the Deadline code.
- Get Jobs In Specified State
Gets jobs in the specified state(s). Valid states are Active, Suspended, Completed, Failed, and Pending. Note that Active covers both Queued and Rendering jobs. Specify more than one state by separating them with commas (ie: Active,Completed,Suspended).
URL: http://hostname:portnumber/api/jobs?States=states
Request Type: GET
Message Body: N/A
Response: JSON object containing all the jobs in the specified state(s).
Possible Errors: 500 Internal Server Error: An exception occurred within the Deadline code.
Get All The Job IDs
URL: http://hostname:portnumber/api/jobs?IdOnly=true
Request Type: GET
Message Body: N/A
Response: JSON object containing all the job IDs in the repository.
Possible Errors: 500 Internal Server Error: An exception occurred within the Deadline code.
- Get Job
Gets job info for the given job ID.
URL: http://hostname:portnumber/api/jobs?JobID=validJobID
Request Type: GET
Message Body: N/A
Response: JSON object containing all the job information for the job ID provided.
Possible Errors: 500 Internal Server Error: An exception occurred within the Deadline code.
- Save Job
Saves the job info provided. Job info must be in JSON format.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = save
- Job = JSON object containing the job info
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no Job entry in the JSON object in the message body.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Suspend Job
Puts the job with the matching ID into the Suspended state.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = suspend
- JobID = the ID of the Job to be suspended
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Suspend Job: Non-rendering tasks
Puts the job with the matching ID into the Suspended state.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = suspendnonrendering
- JobID = the ID of the Job to be suspended
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Resume Job
Resumes the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = resume
- JobID = the ID of the Job to be resumed
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Resume Failed Job
Resumes the failed job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = resumefailed
- JobID = the ID of the failed Job to be resumed
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Requeue Job
Requeues the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = requeue
- JobID = the ID of the Job to be requeued
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Archive Job
Archives the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = archive
- JobID = the ID of the Job to be archived
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Import Job
Imports the job path provided.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = import
- File = the file location of the archived job/s (May be an array)
- The following keys are optional:
- DeleteFile = true (deletes the archive file/s after importing)
Response: The job ids of the imported jobs and of the jobs that were not imported.
- Possible Errors:
- 400 Bad Request: There was no File path provided.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Pend Job
Puts the job with the ID that matches the provided ID in the pending state.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = pend
- JobID = the ID of the Job to be put in the pending state
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Release Pending Job
Releases the job with the ID that matches the provided ID from the pending state.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = releasepending
- JobID = the ID of the Job to be release from the pending state
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Complete Job
Marks the job with the ID that matches the provided ID as complete.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = complete
- JobID = the ID of the Job to be marked as complete
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Fail Job
Marks the job with the ID that matches the provided ID as failed.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = fail
- JobID = the ID of the Job to be marked as failed
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Update Job Submission Date
Updates the Submission Date for the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = updatesubmissiondate
- JobID = the ID of the Job to have the submission date updated for
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Set Job Machine Limit
Sets the Job Machine Limit for the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = setjobmachinelimit
- JobID = the ID of the Job
- The following keys are optional:
- Limit = the new job machine limit, must be an integer
- SlaveList = the Worker(s) to be set as the Worker list (May be an array)
- WhiteListFlag = boolean : sets the allow list flag to true or false
- Progress = Floating point number for the release percentage
Response: “Success”
- Possible Errors:
- 400 Bad Request: There was no JobID entry in the JSON object in the message body.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Add Workers To Job Machine Limit List
Adds the provided Workers to the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = addslavestojobmachinelimitlist
- JobID = the ID of the Job
- SlaveList = the Worker(s) to be added to the Worker list (May be an array)
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- There needs to be at least one Worker passed.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Remove Workers From Job Machine Limit List
Removes the provided Workers from the Job Machine Limit List for the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = removeslavesfromjobmachinelimitlist
- JobID = the ID of the Job
- SlaveList = the Worker(s) to be removed from the Worker list (May be an array)
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- There needs to be at least one Worker passed.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Set Job Machine Limit Listed Workers
Sets provided Workers as Job Machine Limit Listed Workers for the Job whose ID matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = setjobmachinelimitlistedslaves
- JobID = the ID of the Job
- SlaveList = the Worker(s) to be set as the Worker list (May be an array)
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- There needs to be at least one Worker passed.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Set Job Machine Limit Allow List or Deny List Flag
Sets Job Machine Limit Allow List Flag for the job with the ID that matches the provided ID. The flag controls whether the job’s machine limit uses a Worker allow list or deny list. A value of true indicates an allow list, and the Workers in the list are the only Workers allowed to dequeue tasks for the job. A value of false indicates a deny list, and Workers in the list are not allowed to dequeue tasks for the job.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = setjobmachinelimitwhitelistflag
- JobID = the ID of the Job
- WhiteListFlag = boolean : sets the flag to true or false. True for allow list and false for deny list.
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- Must pass a boolean WhiteListFlag.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Set Job Machine Limit
Sets Job Machine Limit Maximum for the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = setjobmachinelimitmaximum
- JobID = the ID of the Job
- Limit = the new job machine limit, must be an integer
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- Must pass an integer Limit
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Set Job Frame Range
Sets the frame range for the job with the ID that matches the provided ID.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = setjobframerange
- JobID = the ID of the Job
- FrameList = the new frame list
- ChunkSize = the new chunk size
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Append Job Frame Range
Appends frames to the job with the ID that matches the provided ID. This adds new tasks without affecting the job’s existing tasks.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = appendjobframerange
- JobID = the ID of the Job
- FrameList = the frame list to append to the job’s existing frames
Response: “Success”
- Possible Errors:
- 400 Bad Request:
- There was no JobID entry in the JSON object in the message body, or
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Job ID provided does not correspond to a Job in the repository.
- Submit Job
Submits a job using the job info provided.
URL: http://hostname:portnumber/api/jobs
Request Type: POST
- Message Body:
- JSON object where the following keys are mandatory:
- JobInfo = JSON object containing the Job Info
- PluginInfo = JSON object containing the Plugin Info
- AuxFiles = Array of Auxiliary File paths (May be empty, but must be provided)
- IdOnly = Set to “true” to only return the job ID (defaults to “false”)
Response: JSON object containing the new Job that was submitted or the Job ID
- Possible Errors:
- 400 Bad Request: Missing one or more of the mandatory keys listed above.
- 500 Internal Server Error:
- An exception occurred within the Deadline code, or
- Could not access the file path specified in NetworkRoot.
- Delete Jobs
Deletes the job corresponding to the job ID provided.
URL: http://hostname:portnumber/api/jobs?JobID=listOfJobIdsToDelete
Request Type: DELETE
Message Body: N/A
Response: “Success”
- Possible Errors:
- 400 Bad Request: Need to provide at least one job ID to delete.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Get Job Details
Gets the Job Details, similar to the Job Details panel, for the Jobs corresponding to the provided Job IDs.
URL: http://hostname:portnumber/api/jobs?JobID=listOfJobIds&Details=true
Request Type: GET
Message Body: N/A
Response: A JSON object containing the Job Details.
- Possible Errors:
- 400 Bad Request: Need to provide at least one job ID to get details for.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Calculate Job Statistics
Calculates Job Statistics for the Jobs corresponding to the provided Job IDs.
URL: http://hostname:portnumber/api/jobs?JobID=listOfJobIds&Statistics=true
Request Type: GET
Message Body: N/A
Response: A JSON object containing the Job Statistics.
- Possible Errors:
- 400 Bad Request: Need to provide at least one job ID to get statistics for.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Get Deleted Jobs
Gets the Deleted Jobs that correspond to the provided Job IDs.
URL: http://hostname:portnumber/api/jobs?JobID=listOfJobIds&Deleted=true
Request Type: GET
Message Body: N/A
Response: A JSON object containing the deleted Jobs.
- Possible Errors:
- 400 Bad Request: Need to provide at least one deleted job ID.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Get All Deleted Jobs
Gets all the Deleted Jobs.
URL: http://hostname:portnumber/api/jobs?Deleted=true
Request Type: GET
Message Body: N/A
Response: A JSON object containing the deleted Jobs.
Possible Errors: 500 Internal Server Error: An exception occurred within the Deadline code.
- Purge Deleted Jobs
Purges the Deleted Jobs that correspond to the provided Job IDs.
URL: http://hostname:portnumber/api/jobs?JobID=listOfJobIdsToDelete&Purge=true
Request Type: DELETE
Message Body: N/A
Response: “Success”
- Possible Errors:
- 400 Bad Request: Need to provide at least one job ID to delete.
- 500 Internal Server Error: An exception occurred within the Deadline code.
- Undelete Jobs
Undeletes the Deleted Jobs that correspond to the provided Job IDs.
URL: http://hostname:portnumber/api/jobs
Request Type: PUT
- Message Body:
- JSON object where the following keys are mandatory:
- Command = undelete
- JobID/s = job ID/list of job IDs to undelete
Response: “Success”
- Possible Errors:
- 400 Bad Request: Need to provide at least one job ID to delete.
- 500 Internal Server Error: An exception occurred within the Deadline code.
Job Property Values¶
Values for some Job properties are represented by numbers. Those properties and their possible values are listed below.
- Stat (Status)
- 0 = Unknown
- 1 = Active
- 2 = Suspended
- 3 = Completed
- 4 = Failed
- 6 = Pending
Note that an active job can either be idle or rendering. Use the RenderingChunks property to determine if anything is rendering.
- Timeout (OnTaskTimeout)
- 0 = Both
- 1 = Error
- 2 = Notify
- OnComp (OnJobComplete)
- 0 = Archive
- 1 = Delete
- 2 = Nothing
- Schd (ScheduledType)
- 0 = None
- 1 = Once
- 2 = Daily