Run a job

Run one command on its own fresh GPU machine. Runcrate launches the machine, runs the command with bash in /workspace, streams its output to GET /jobs/{id}/logs, and stops the machine as soon as the command exits, hits max_runtime_minutes or is cancelled. Files written under /workspace are saved back to the volume (storage_id) when the machine stops. The machine also shows in GET /instances while it runs. If the machine could not be launched after the job was created, the error has details.job_id and that job is failed.

POST

jobs

Run a job

curl --request POST \
  --url https://www.runcrate.ai/api/v1/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "<string>",
  "gpu_type": "<string>",
  "max_runtime_minutes": 720,
  "gpu_count": 1,
  "template": "ubuntu-devbox",
  "image": "<string>",
  "env": {},
  "storage_id": "<string>",
  "name": "<string>",
  "region": "<string>"
}
'

import requests

url = "https://www.runcrate.ai/api/v1/jobs"

payload = {
    "command": "<string>",
    "gpu_type": "<string>",
    "max_runtime_minutes": 720,
    "gpu_count": 1,
    "template": "ubuntu-devbox",
    "image": "<string>",
    "env": {},
    "storage_id": "<string>",
    "name": "<string>",
    "region": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    command: '<string>',
    gpu_type: '<string>',
    max_runtime_minutes: 720,
    gpu_count: 1,
    template: 'ubuntu-devbox',
    image: '<string>',
    env: {},
    storage_id: '<string>',
    name: '<string>',
    region: '<string>'
  })
};

fetch('https://www.runcrate.ai/api/v1/jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.runcrate.ai/api/v1/jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'command' => '<string>',
    'gpu_type' => '<string>',
    'max_runtime_minutes' => 720,
    'gpu_count' => 1,
    'template' => 'ubuntu-devbox',
    'image' => '<string>',
    'env' => [
        
    ],
    'storage_id' => '<string>',
    'name' => '<string>',
    'region' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.runcrate.ai/api/v1/jobs"

	payload := strings.NewReader("{\n  \"command\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"max_runtime_minutes\": 720,\n  \"gpu_count\": 1,\n  \"template\": \"ubuntu-devbox\",\n  \"image\": \"<string>\",\n  \"env\": {},\n  \"storage_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"region\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.runcrate.ai/api/v1/jobs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"max_runtime_minutes\": 720,\n  \"gpu_count\": 1,\n  \"template\": \"ubuntu-devbox\",\n  \"image\": \"<string>\",\n  \"env\": {},\n  \"storage_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"region\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.runcrate.ai/api/v1/jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"max_runtime_minutes\": 720,\n  \"gpu_count\": 1,\n  \"template\": \"ubuntu-devbox\",\n  \"image\": \"<string>\",\n  \"env\": {},\n  \"storage_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"region\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "queued",
    "command": "<string>",
    "gpu_type": "<string>",
    "gpu_count": 4,
    "env_keys": [
      "<string>"
    ],
    "max_runtime_minutes": 720,
    "created_at": "2023-11-07T05:31:56Z",
    "template": "<string>",
    "image": "<string>",
    "storage_id": "<string>",
    "exit_code": 123,
    "error": "<string>",
    "instance_id": "<string>",
    "environment_id": "<string>",
    "started_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "cost_per_hour": 123,
    "cost_usd": 123,
    "log_bytes": 123,
    "logs_truncated": true
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Use a Runcrate API key with the rc_live_* prefix as the bearer token. Create one at https://www.runcrate.ai/dashboard/api-keys.

Body

application/json

command

string

required

Shell command, run with bash in /workspace. At most 65536 bytes.

Minimum string length: 1

gpu_type

string

required

GPU model (e.g. A4000, H100), as listed by GET /instances/types.

max_runtime_minutes

integer

required

Longest the command may run, counted from when it starts. Required: a job never runs unbounded.

Required range: 1 <= x <= 1440

gpu_count

integer

default:1

Required range: 1 <= x <= 8

template

string

default:ubuntu-devbox

OS template id from GET /templates.

image

string

Container image to run the command in. /workspace is mounted and the image is pulled before the max runtime starts. The GPUs are passed into the container only on machines with the NVIDIA container runtime; otherwise the job log says so and the command runs without GPUs. The image needs bash or sh.

env

object

Environment variables for the command, as { "KEY": "value" }, added to the environment's secrets (a name set in both takes this value). Keys match ^[A-Za-z_][A-Za-z0-9_]*$ and don't start with RUNCRATE_; at most 200 keys, values up to 32 KB, 64 KB in total with the secrets. Values are stored only encrypted and never returned.

Show child attributes

storage_id

string

Volume to mount at /workspace. Must be in the same workspace and environment and not attached to another machine.

name

string

Defaults to job-<first 8 chars of id>.

Maximum string length: 63

region

string

Preferred region.

Response

Job created with status queued.

data

object

required

One command run on its own fresh GPU machine. The machine stops, and billing ends, as soon as the command exits, hits max_runtime_minutes or is cancelled.

Show child attributes

Run a job

curl --request POST \
  --url https://www.runcrate.ai/api/v1/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "<string>",
  "gpu_type": "<string>",
  "max_runtime_minutes": 720,
  "gpu_count": 1,
  "template": "ubuntu-devbox",
  "image": "<string>",
  "env": {},
  "storage_id": "<string>",
  "name": "<string>",
  "region": "<string>"
}
'

import requests

url = "https://www.runcrate.ai/api/v1/jobs"

payload = {
    "command": "<string>",
    "gpu_type": "<string>",
    "max_runtime_minutes": 720,
    "gpu_count": 1,
    "template": "ubuntu-devbox",
    "image": "<string>",
    "env": {},
    "storage_id": "<string>",
    "name": "<string>",
    "region": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    command: '<string>',
    gpu_type: '<string>',
    max_runtime_minutes: 720,
    gpu_count: 1,
    template: 'ubuntu-devbox',
    image: '<string>',
    env: {},
    storage_id: '<string>',
    name: '<string>',
    region: '<string>'
  })
};

fetch('https://www.runcrate.ai/api/v1/jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.runcrate.ai/api/v1/jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'command' => '<string>',
    'gpu_type' => '<string>',
    'max_runtime_minutes' => 720,
    'gpu_count' => 1,
    'template' => 'ubuntu-devbox',
    'image' => '<string>',
    'env' => [
        
    ],
    'storage_id' => '<string>',
    'name' => '<string>',
    'region' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.runcrate.ai/api/v1/jobs"

	payload := strings.NewReader("{\n  \"command\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"max_runtime_minutes\": 720,\n  \"gpu_count\": 1,\n  \"template\": \"ubuntu-devbox\",\n  \"image\": \"<string>\",\n  \"env\": {},\n  \"storage_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"region\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.runcrate.ai/api/v1/jobs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"max_runtime_minutes\": 720,\n  \"gpu_count\": 1,\n  \"template\": \"ubuntu-devbox\",\n  \"image\": \"<string>\",\n  \"env\": {},\n  \"storage_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"region\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.runcrate.ai/api/v1/jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"max_runtime_minutes\": 720,\n  \"gpu_count\": 1,\n  \"template\": \"ubuntu-devbox\",\n  \"image\": \"<string>\",\n  \"env\": {},\n  \"storage_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"region\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "queued",
    "command": "<string>",
    "gpu_type": "<string>",
    "gpu_count": 4,
    "env_keys": [
      "<string>"
    ],
    "max_runtime_minutes": 720,
    "created_at": "2023-11-07T05:31:56Z",
    "template": "<string>",
    "image": "<string>",
    "storage_id": "<string>",
    "exit_code": 123,
    "error": "<string>",
    "instance_id": "<string>",
    "environment_id": "<string>",
    "started_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "cost_per_hour": 123,
    "cost_usd": 123,
    "log_bytes": 123,
    "logs_truncated": true
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Chat

Images

Videos

Audio

Embeddings

Models

Instances

Jobs

Schedules

Storage

Environments

Secrets

SSH Keys

Templates

Billing

Run a job

Authorizations

Body

Response