Posting a Job

Jobs are created and added to the queue by sending a POST request to the Job Queue API at https://api.salad.com/api/public/organizations/{organization_name}/projects/{project_name}/queues/{queue_name}/jobs

📘 Using the SaladCloud API

SaladCloud offers a full API to access all of the functionality of the Portal, as well as additional features (such as adding Jobs to the Job Queue!). You can learn more about authentication and how to use the SaladCloud API here.

Job Structure

Input

The request should include an "input": { ... } which must be valid JSON. This is the information passed to your application running in the container.

Metadata (optional)

The response will include a unique call id generated by SaladCloud that can be used to retrieve your results. If you wish to attach your own id to the job for tracking purposes, you may include it in an optional, arbitrary "metadata": { ... } object. Note that metadata must be a valid JSON object, as opposed to the input which may be any JSON format (string, object, number, etc.).

📘 JSON output

The Queue Worker expects valid JSON input (that it will pass to your application), as well as valid JSON output (completed results that it sends up to the Job Queue). Please ensure that your application returns JSON-formatted results.


Example Job

{
  "metadata": {
    "id": "my-custom-id-123"
  },
  "input": {
    "width": 640,
    "height": 480,
    "iterations": 10,
    "re_min": -2,
    "re_max": 1,
    "im_min": -1,
    "im_max": 1,
    "kind": "base64"
  }
}

Example Response

{
  "id": "50150edd-e182-47b5-a754-2d2a04d6ee31",
  "input": {
    "width": 640,
    "height": 480,
    "iterations": 10,
    "re_min": -2,
    "re_max": 1,
    "im_min": -1,
    "im_max": 1,
    "kind": "base64"
  },
  "metadata": {
    "id": "my-custom-id-123"
  },
  "status": "pending",
  "events": [
    {
      "action": "created",
      "time": "2024-01-20T01:02:48.4787553+00:00"
    }
  ],
  "create_time": "2024-01-20T01:02:48.4787553+00:00",
  "update_time": "2024-01-20T01:02:48.4787553+00:00"
}

Note the Salad-generated "id" field. We will use this in the next step when we check the status of the job and retrieve results.

Getting the status of a Job

To check the status of a job, you will first need its id. The id is a string that is provided on the response object when you created the job.

In our previous example, we saw the id returned on the response object was 50150edd-e182-47b5-a754-2d2a04d6ee31

Check the status of a job by sending a GET request to https://api.salad.com/api/public/organizations/{organization_name}/projects/{project_name}/queues/{queue_name}/jobs/{id}

Interpreting the Job status

Here is an example response when checking the Job status for job id 50150edd-e182-47b5-a754-2d2a04d6ee31:

{
  "id": "50150edd-e182-47b5-a754-2d2a04d6ee31",
  "input": {
    "width": 640,
    "height": 480,
    "iterations": 10,
    "re_min": -2,
    "re_max": 1,
    "im_min": -1,
    "im_max": 1,
    "kind": "base64"
  },
  "metadata": {
    "id": "my-custom-id-123"
  },
  "webhook": "https://callback.example.com/result",
  "status": "pending",
  "events": [
    {
      "action": "created",
      "time": "2024-01-20T01:02:48.4787553+00:00"
    }
  ],
  "create_time": "2024-01-20T01:02:48.4787553+00:00",
  "update_time": "2024-01-20T01:02:48.4787553+00:00"
}

"status" of the job can be:

  • pending - The job has been added to the queue and is waiting to be run
  • running - The job has been popped from the queue and dispatched to a workload instance for processing.
  • succeeded - The job has been run and the response has been received.
  • cancelled - The job was cancelled before it was dispatched to a workload instance. Note: a job cannot be cancelled once it has been dispatched.
  • failed - The job was retried three times and failed to run to completion. Note: once a job has reached a failed status, it will not be retried and instead must be resubmitted to the queue.

Viewing results

Once the job has finished, the results will be available on this response object, and at the webhook URL (if provided).