Skip to main content
POST
/
compute
/
instances
Create Compute Instance
curl --request POST \
  --url https://api.fal.ai/v1/compute/instances \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "instance_type": "gpu_8x_h100_sxm5",
  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host",
  "sector": "sector_1"
}'
{
  "id": "inst_abc123xyz",
  "instance_type": "gpu_8x_h100_sxm5",
  "region": "us-west",
  "sector": "sector_1",
  "status": "provisioning",
  "creator_user_nickname": "developer"
}

Authorizations

​
Authorization
string
header
required

Admin API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_ADMIN_API_KEY

Headers

​
Idempotency-Key
string

Optional idempotency key for safe request retries

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Request body for creating a new compute instance with SSH access

​
instance_type
enum<string>
required

Type of compute instance to create

Available options:
gpu_8x_h100_sxm5,
gpu_1x_h100_sxm5
Example:

"gpu_1x_h100_sxm5"

​
ssh_key
string
required

SSH public key for accessing the instance (e.g., 'ssh-rsa AAAAB3...')

Minimum length: 1
Example:

"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC... user@host"

​
sector
enum<string>

Sector for InfiniBand configuration (only valid with gpu_8x_h100_sxm5)

Available options:
sector_1,
sector_2,
sector_3
Example:

"sector_1"

Response

Compute instance created successfully

Compute instance details including configuration, location, and status

​
id
string
required

Unique identifier for the compute instance

Example:

"inst_abc123xyz"

​
instance_type
enum<string>
required

Type of compute instance (GPU configuration)

Available options:
gpu_8x_h100_sxm5,
gpu_1x_h100_sxm5
Example:

"gpu_1x_h100_sxm5"

​
region
enum<string>
required

Geographical region where the instance is located

Available options:
us-west,
us-central,
us-east,
eu-north,
eu-west,
other
Example:

"us-west"

​
status
enum<string>
required

Current operational status of the instance

Available options:
ready,
init,
pending,
provisioning,
stopped,
unknown
Example:

"ready"

​
sector
enum<string>

Sector identifier for instance placement within the region (if applicable)

Available options:
sector_1,
sector_2,
sector_3
Example:

"sector_1"

​
ip
string

IP address of the instance (available when instance is ready)

Example:

"203.0.113.42"

​
creator_user_nickname
string

Nickname of the user who created this instance

Example:

"developer"