Jobs

A job is a function (and its corresponding settings) that is paired with one or more input files and is ready for processing (e.g. an input video and a point cloud reconstruction function, or a set of images and a textured mesh reconstruction function).

Create a new job

Create a new job.

Route: /v3{instance-uri}/jobs
Method: POST

Sample request body:

{
  "function": "/functions/pixels-to-point-cloud",
  "inputs": [
    "/images/1111-1111",
    "/images/2222-2222",
    "/images/3333-3333",
    ...
  ],
  "settings": {
    "output_file_types": ["ply"]
  },
  "custom_attributes": {
    "my_attribute": "My custom attribute value."
  },
  "priority": 0
}

Description of the request attributes:

• "function" - URI of the selected function.
• "inputs" - List of file URIs to use as input when running the function.
• "settings" - Optional dictionary of key/value pairs specifying the settings to use for the function.
• "custom_attributes" - Optional dictionary of custom attribute names and values to set for the job.
• "priority" - Optional integer to set the scheduling priority of a job relative to other pending jobs within an account. When evaluating which job to run next, the API first selects a job with the highest priority, and then breaks ties based on the order in which the jobs were created. The default priority is 0, and both positive and negative values are allowed.

Upon successful creation of a job, the response will contain the details of the newly created job.

Get a list of jobs

Returns a list of all jobs. Each job in the list is represented by its URI.

Route: /v3{instance-uri}/jobs
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "jobs": [
      "/jobs/1111-1111",
      "/jobs/2222-2222",
      "/jobs/3333-3333",
      ...
    ]
  }
}

Get details of a job

Get the details of an individual job.

Route: /v3{instance-uri}{job-uri}
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "job": {
      "uri": "/jobs/1234-5678",
      "status": "complete",
      "priority": 0,
      "inputs": [
        "/images/1111-1111",
        "/images/2222-2222",
        "/images/3333-3333",
        ...
      ],
      "outputs": [
        "/point-clouds/1111-1111"
      ],
      "function": "/functions/pixels-to-point-cloud",
      "settings": {
        "output_file_types": ["ply"]
      },
      "custom_attributes": {
        "my_attribute": "My custom attribute value."
      }
    }
  }
}

Description of response attributes:

• "uri" - Resource identifier for this job.
• "status" - The status of the job. It can be any one of the following values:
  • "pending" - Processing has not yet started.
  • "processing" - Processing is currently running.
  • "complete" - Processing has finished.
  • "failed" - Processing failed to complete successfully.
• "priority" - Scheduling priority of a job relative to other pending jobs within an account. When evaluating which job to run next, the API first selects a job with the highest priority, and then breaks ties based on the order in which the jobs were created. The default priority is 0, and both positive and negative values are allowed.
• "inputs" - List of input file URIs.
• "outputs" - List of output file URIs. This will be null until processing has finished successfully (e.g. "status" is "complete").
• "function" - URI of the selected function.
• "settings" - Dictionary of key/value pairs specifying the settings to use for the function.
• "custom_attributes" - Dictionary with custom attribute names and values that have been defined for this job.

In the case that the job failed (e.g. "status" is "failed"), there will be an additional "error" response attribute with the following information:

• "code" - Integer value that corresponds to one of the runtime error codes.
• "message" - Human-readable summary of the failure.
• "details" - Any additional details about the failure that may be available.

Update a job

Update the details of a job.

Route: /v3{instance-uri}{job-uri}
Method: PATCH

Once a job is created, the only details of a job that can be updated are its custom attributes and the "priority" property. The custom attributes are updated using the same syntax as a file's custom attributes. In a similar manner, the "priority" property is updated by including a new value in the body of the request.

Sample request body:

{
  "priority": 1,
  "custom_attributes": {
    "my_attribute": "An updated value."
  }
}

Upon successfully updating a job, the response will contain the updated details of the job.

Delete a job

Remove a job from the API.

Route: /v3{instance-uri}{job-uri}
Method: DELETE

Sample response body:

{
  "success": true
}

Custom attributes

Jobs support the use of custom attributes. Initial values for custom attributes can be assigned when the job is created, though they can always be set and updated at a later time.

Querying

Similar to files, querying can be used to search for jobs. Queries for jobs can be performed using the "status" or "priority" properties, as well as with any custom attribute that has been defined. To perform a query, a query string is appended to the jobs endpoint:

Route: /v3{instance-uri}/jobs?q={query-string}
Method: GET

The types of query operations that are supported (along with their syntax) is the same as what is available when querying for files. The only exception is that jobs can only be queried using properties that are specific to jobs as well as custom attributes (standard attributes and file properties are not applicable).