Get Compute Instance

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

Requirements:

Requires compute permissions (extra_permissions.compute = true)
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.

Required permissions: compute:instances:read. Key presets that include them: COMPUTE, READONLY, FULL. See key permissions.

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

Key on the READONLY preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_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"

⌘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"
  }
}