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)
Authentication required via admin API key

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.

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

Admin API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_ADMIN_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

Show child attributes

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