List Compute Instances

Returns a list of all compute instances belonging to the authenticated user’s workspace.

Requirements:

Requires compute permissions (extra_permissions.compute = true)

Key Features:

View all instances regardless of status
Includes instance configuration, region, and current status
Paginated results for large instance lists

Common Use Cases:

Monitor all active compute resources
Check instance status and availability
Audit compute resource usage
Build compute management dashboards

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

List Compute Instances

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

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

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

{
  "instances": [
    {
      "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"
    },
    {
      "id": "inst_def456uvw",
      "instance_type": "gpu_8x_h100_sxm5",
      "region": "us-east",
      "status": "provisioning",
      "creator_user_nickname": "developer"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

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

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

{
  "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

Query Parameters

limit

integer

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Required range: x >= 1

Example:

50

cursor

string

Pagination cursor from previous response. Encodes the page number.

Example:

"Mg=="

Response

Successfully retrieved compute instances

Response containing a list of compute instances with pagination support

next_cursor

string | null

required

Cursor for the next page of results, null if no more pages

has_more

boolean

required

Boolean indicating if more results are available (convenience field derived from next_cursor)

instances

object[]

required

Array of compute instances belonging to the authenticated user

Hide child attributes

instances.id

string

required

Unique identifier for the compute instance

Example:

"inst_abc123xyz"

instances.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"

instances.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"

instances.status

enum<string>

required

Current operational status of the instance

Available options:

ready,

init,

pending,

provisioning,

stopped,

unknown

Example:

"ready"

instances.sector

enum<string>

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

Available options:

sector_1,

sector_2,

sector_3

Example:

"sector_1"

instances.ip

string

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

Example:

"203.0.113.42"

instances.creator_user_nickname

string

Nickname of the user who created this instance

Example:

"developer"

⌘I

List Compute Instances

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

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

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

{
  "instances": [
    {
      "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"
    },
    {
      "id": "inst_def456uvw",
      "instance_type": "gpu_8x_h100_sxm5",
      "region": "us-east",
      "status": "provisioning",
      "creator_user_nickname": "developer"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

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

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

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

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