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

Get Compute InstanceRetrieves 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](https://docs.fal.ai/compute) for more details.

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