Skip to main content
POST
Create a GPU instance

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.

Headers

Idempotency-Key
string

Required with term_months (400 without it): names the purchase, so a retried request never buys a second term. Sending the same key again answers 200 with the instance it already bought and Idempotent-Replayed: true; no second debit or machine. A key whose term was returned (its instance never started) answers 409: use a new key.

Maximum string length: 255

Body

application/json

Provide either gpu_type (Runcrate picks an available configuration for that GPU. When the best-priced option's starts are failing, it may pick one up to 10% dearer that is starting reliably; the response shows the price you'll pay (cost_per_hour).) or instance_type_id (specific config from /instances/types).

name
string
required

Human-readable instance name.

gpu_type
string

GPU model id (e.g. H100). Required if instance_type_id is not provided. H200 takes either H200 card, SXM or NVL, and the instance's gpu_type says which (H200 or H200_nvl); H200_sxm asks for the SXM card only, H200_nvl for the NVL only.

instance_type_id
string

Exact instance-type id from GET /instances/types. Required if gpu_type is not provided. The id alone is enough: the type sets the GPU count. A gpu_count sent with it must be the type's gpu_count, or the request is refused with a 400.

include_community
boolean
default:false

Let a community host run it (host_tier: community). Off by default: only datacenter machines are picked, and a community instance_type_id is refused. Never with term_months. Refused with 409 sensitive_secrets_on_community_host while the environment has Sensitive secrets: they are never sent to a community host.

include_spot
boolean
default:false

Let a spot machine run it (capacity_tier: spot): cheaper, but its host may reclaim it after reclaim_notice_minutes of notice, and the instance then ends. Off by default: a spot instance_type_id is refused.

eea_only
boolean
default:false

Run it only on a machine whose address is registered in the European Economic Area (the EU, Iceland, Liechtenstein and Norway). Only types whose region positively names an EEA country are offered. The first check of the machine's address runs after the machine is rented: an address registered anywhere else, or that cannot be verified, is released before it runs and is never charged, and the launch moves to the next option. When none is left the instance fails with No machine in the European Economic Area could be verified for this launch; nothing was charged. The secrets the machine pulls from Runcrate, and its other machine calls, are served only to an address registered in the EEA. The launch script itself (your startup commands) is on most machine types sent when the machine is created, so it is already on the host when the check runs; on the others it is sent only after the address passes. So eea_only filters where machines are rented and is not a guarantee of where your data is processed, and it reads where an address is registered, not exactly where the machine stands. With storage_id, only machine types that receive the script after the address is checked are offered; otherwise the request is refused with a 400 (A volume cannot be attached to an eea_only launch on this machine type yet) and nothing is rented. Off by default. Also a field of schedules and jobs; not supported on clusters.

region
string

Only launch in this region: a region from GET /instances/types, the start of one (us-east), or a city or country (canada). If nothing is available there the request fails and names the regions that have it; it never launches elsewhere. Defaults to auto (any region).

gpu_count
enum<integer>

GPUs on the machine: 1, 2, 4 or 8. Any other count is refused with a 400.

Available options:
1,
2,
4,
8
cpu_cores
integer
Required range: x >= 1
memory
integer

GB

Required range: x >= 1
storage
integer

GB ephemeral storage

Required range: x >= 1
template
string

Template id to boot from.

ssh_key_id
string

ID of an SSH key to inject (create one via POST /ssh-keys).

env_vars
object[]

Environment variables for this launch, added to the environment's secrets (a name set in both takes this value). Each item is { "key": "NAME", "value": "..." }: names are letters, digits and underscores, not starting with a digit or RUNCRATE_; values up to 32 KB, 64 KB in all. They are stored encrypted, never returned, and the machine reads them at boot from /etc/runcrate/secrets.env.

startup_commands
string[]

Commands run after setup. Together with launch_script, about 2.8 KB once gzip-compressed at most (shell usually compresses 3 to 4 times).

storage_id
string

Persistent volume to attach at boot. Mounts at /workspace.

launch_script
string

Raw shell script to run on boot. Together with startup_commands, about 2.8 KB once gzip-compressed at most (shell usually compresses 3 to 4 times). Put a longer script in a file on a volume and run that.

launch_script_base64
string

Base64-encoded launch script (alternative to launch_script).

max_runtime_minutes
integer | null

Terminate the instance automatically this many minutes after it starts running (5 to 10080). An alert goes out 10 minutes before. Omit for no limit. Recommended for unattended or agent-run work.

Required range: 5 <= x <= 10080
idle_shutdown_minutes
integer | null

Terminate the instance once GPU utilization stays under 5% with nobody connected (SSH, web terminal or code editor) for this many minutes (5 to 1440). GPU instances only. Omit to leave it off.

Required range: 5 <= x <= 1440
term_months
enum<integer>

Buy a prepaid term for this instance at the discount listed in subscription_terms of GET /instances/types (a length the type does not list is refused with 409 and details.reason: term_not_offered), paid in full from credit when the instance is created. Requires an Idempotency-Key header (or idempotency_key) and expected_total_price. Refused (403) for an agent sign-in (MCP or CLI agent token), with a message the agent can relay: a person buys the term in the dashboard. API keys can buy. The term starts when the GPU is running and can't be cancelled: the instance can't be terminated before it ends, and the unused time comes back as credit only if Runcrate ends it early or its machine is lost. A term of 3 months or more, or over $1,000, needs a verified identity (dashboard, once per account). Not allowed with max_runtime_minutes or idle_shutdown_minutes. Omit for hourly billing.

Available options:
1,
3,
6,
12
expected_total_price
number

Required with term_months: the term's total_price from subscription_terms of GET /instances/types, in USD. If the price differs by $0.01 or more when the instance is created, nothing is bought and the answer is 409 with details.reason: price_changed and the current details.total_price_usd.

expected_hourly_rate
number

On demand (without term_months): the hourly_rate you were shown in GET /instances/types, in USD. If the live price is more than 2% above it when the instance is created, nothing launches and the answer is 409 with details.reason: price_changed, the live details.hourly_rate_usd and the details.expected_hourly_rate_usd you sent; send the new rate to launch at it. A lower live price launches at the lower price. Omit it to launch at the live price.

idempotency_key
string

Same as the Idempotency-Key header, for clients that cannot set headers. Required with term_months (one of the two).

Maximum string length: 255

Response

A replay of an earlier term_months request with the same Idempotency-Key: the instance that request bought, with Idempotent-Replayed: true. Nothing is charged again.

data
object
required