Get Compute Instance

Retrieves detailed information about a specific compute instance by its ID.

Requirements:

Requires compute permissions (extra_permissions.compute = true)
Authentication required via admin API key
Instance must belong to the authenticated user’s workspace

Key Features:

Get current instance status and configuration
Access instance IP address when available
View region and sector placement
Check creator information

Common Use Cases:

Monitor specific instance status
Retrieve connection details (IP address)
Check instance readiness before use
Audit instance configuration

See fal.ai docs for more details.

GET

compute

instances

{id}

Get Compute Instance

curl --request GET \
  --url https://api.fal.ai/v1/compute/instances/{id} \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/compute/instances/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "inst_abc123xyz",
  "instance_type": "gpu_1x_h100_sxm5",
  "region": "us-west",
  "sector": "sector_1",
  "ip": "203.0.113.42",
  "status": "ready",
  "creator_user_nickname": "developer"
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Unique identifier for the compute instance

Minimum string length: 1

Example:

"inst_abc123xyz"

Response

Successfully retrieved compute instance details

Compute instance details including configuration, location, and status

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"

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"

Create Compute InstanceCreates a new compute instance with the specified configuration and SSH key. **Requirements:** - Requires compute permissions (extra_permissions.compute = true) - Authentication required via admin API key - Valid SSH public key required for instance access **Key Features:** - Create high-performance GPU instances - Specify sector for InfiniBand configuration (8x H100 only) - SSH key-based authentication - Automatic instance provisioning and region assignment - Idempotent creation with Idempotency-Key header (optional but recommended) **Common Use Cases:** - Spin up compute resources for ML training - Create GPU instances for inference workloads - Set up development environments with H100 GPUs - Deploy distributed training with InfiniBand networking **Instance Types:** - `gpu_8x_h100_sxm5`: 8x NVIDIA H100 GPUs (high-performance, supports sector configuration for InfiniBand) - `gpu_1x_h100_sxm5`: 1x NVIDIA H100 GPU (standard) **Idempotency:** - Optional Idempotency-Key header prevents duplicate instance creation on retries - Responses cached for 10 minutes per unique key See [fal.ai docs](https://docs.fal.ai/compute) for more details.

⌘I

Get Compute Instance

curl --request GET \
  --url https://api.fal.ai/v1/compute/instances/{id} \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/compute/instances/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "inst_abc123xyz",
  "instance_type": "gpu_1x_h100_sxm5",
  "region": "us-west",
  "sector": "sector_1",
  "ip": "203.0.113.42",
  "status": "ready",
  "creator_user_nickname": "developer"
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}