Skip to content
fal.ai Docs
Dashboard

Compute API

REST API for managing compute instances on the fal platform.

Authentication

All API requests require authentication using a fal API key.

Header Format

Authorization: Key <FAL_ADMIN_API_KEY>

Getting Your API Key

  1. Navigate to the fal dashboard keys page
  2. Generate a key from the UI
  3. Choose the admin scope for compute

Base URL

https://rest.alpha.fal.ai

Endpoints

1. List All Instances

GET /compute/instances

Returns a list of all compute instances.

Terminal window
curl -X GET "https://rest.alpha.fal.ai/compute/instances" \
  -H "Authorization: Key <YOUR_FAL_ADMIN_API_KEY>"

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "instance_type": "gpu_1x_h100_sxm5",
    "ip": "192.168.1.100",
    "status": "ready"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "instance_type": "gpu_8x_h100_sxm5",
    "sector": "sector_2",
    "ip": "192.168.1.101",
    "status": "provisioning"
  }
]

2. Get Instance Details

GET /compute/instance/{instance_id}

Retrieves details for a specific compute instance.

Terminal window
curl -X GET "https://rest.alpha.fal.ai/compute/instance/your-instance-id" \
  -H "Authorization: Key <YOUR_FAL_ADMIN_API_KEY>"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "instance_type": "gpu_1x_h100_sxm5",
  "ip": "192.168.1.100",
  "status": "ready"
}

3. Create Instance

POST /compute/instance

Creates a new compute instance.

Request Body:

{
  "instance_type": "gpu_8x_h100_sxm5",
  "ssh_key": "ssh-rsa ...",
}

Parameters:

  • instance_type (required): The type of compute instance. Valid values:
    • gpu_8x_h100_sxm5 - 8x H100 SXM5 GPUs
    • gpu_1x_h100_sxm5 - 1x H100 SXM5 GPU
  • ssh_key (required): SSH public key for instance access
  • sector (optional): Specific sector configuration for infiniband. Only valid with gpu_8x_h100_sxm5 Valid values:
    • sector_1
    • sector_2
    • sector_3

Example:

Terminal window
curl -X POST "https://rest.alpha.fal.ai/compute/instance" \
  -H "Authorization: Key <YOUR_FAL_ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_type": "gpu_1x_h100_sxm5",
    "ssh_key": "ssh-rsa ...",
  }'

4. Delete Instance

DELETE /compute/instance/{instance_id}

Deletes a specific compute instance.

Terminal window
curl -X DELETE "https://rest.alpha.fal.ai/compute/instance/your-instance-id" \
  -H "Authorization: Key <YOUR_FAL_ADMIN_API_KEY>"

Response Format

ComputeInstance Object

All instance-related endpoints return a ComputeInstance object or array of objects with the following structure:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "instance_type": "gpu_1x_h100_sxm5",
  "ip": "192.168.1.100",
  "status": "ready"
}

Fields:

  • id: Unique identifier (UUID) for the instance
  • instance_type: Type of compute instance (see available types above)
  • sector: Sector configuration (can be null)
  • ip: IP address of the instance (can be null if not yet assigned)
  • status: Current status of the instance

Instance Status Values

  • ready - Instance is ready for use
  • init - Instance is initializing
  • pending - Instance creation is pending
  • provisioning - Instance is being provisioned
  • unknown - Status is unknown

Quick Start

  1. Get your API key from fal.ai/dashboard/keys with ADMIN scope
  2. List existing instances to see your current setup
  3. Create a new instance with your preferred configuration
  4. Monitor and manage your instances as needed