Lambda Cloud API

The Lambda Cloud API provides a set of REST API endpoints you can use to create and manage your Lambda Cloud resources.

Requests to the API are generally limited to one request per second. Requests to the /instance-operations/launch endpoint are limited to one request per 12 seconds, or five requests per minute.

Download OpenAPI spec 1.10.0

Response types and formats

The format of each response object depends on whether the request succeeded or failed.

Success responses

When a request succeeds, the API returns a response object in the following format. <PAYLOAD> represents the endpoint-specific data object returned as part of the response object.

{
    "data": <PAYLOAD>
}

Error responses

When a request fails, the API returns an error response object in the following format:

{
    "error": {
        "code": string,
        "message": string,
        "suggestion": string?
    }
}

• code: A machine- and human-readable error code specific to a particular failure mode.
• message: An explanation of the error.
• suggestion: When present, a suggestion for how to address the error.

info

Note

When handling errors, avoid relying on the values of message or suggestion, as these values are subject to change. Instead, use the value of code.

Provider errors

In some cases, you might receive errors that come from upstream services/providers rather than directly from Lambda services. You can identify these errors by their error code prefix, provider/.

Common provider errors include:

• Network outages or connectivity issues
• Service unavailability
• Quota limitations or resource exhaustion

An example of a typical service unavailability error:

{
  "error": {
    "code": "provider/internal-unavailable",
    "message": "Provider unavailable",
    "suggestion": "Try again shortly"
  }
}

Outgoing webhooks

Lambda can send webhook notifications to your URL when support ticket events occur, enabling near real-time integration with your systems.

Event types

• ticket.created - A support ticket was created.
• ticket.status_changed - A support ticket's status was updated, and the ticket remains open.
• ticket.resolved - A support ticket's status was set to solved, or the ticket was closed.

Payload structure

All webhook payloads follow this structure:

{
  "id": "a3b7c9d1e5f642a8b0c2d4e6f8a0b2c4",
  "object": "event",
  "type": "ticket.created",
  "created": 1700000000,
  "api_version": "2025-11-18",
  "data": {
    "object": "ticket",
    "id": "f1e2d3c4b5a647869708192a3b4c5d6e",
    "subject": "Issue with instance 0920582c7ff041399e34823a0be62549",
    "description": "Detailed description of the issue...",
    "request_type": "incident",
    "severity": "sev_2",
    "status": "new",
    "created_at": "2024-11-15T10:00:00+00:00",
    "updated_at": "2024-11-15T10:00:00+00:00",
    "instance_ip": "192.168.1.100",
    "instance_id": "0920582c7ff041399e34823a0be62549",
    "cluster_id": null,
    "source": "api"
  }
}

Webhook authentication

Webhook requests include a Bearer token in the Authorization header for authentication:

Authentication

The Lambda Cloud API uses API keys to authenticate incoming requests. You can generate a new API key pair or view your existing API keys by visiting the API keys page in the Lambda Cloud dashboard.

In general, Lambda recommends passing an HTTP Bearer header that contains your API key:

Authenticating with curl

Pass your API key in the Authorization header using the Bearer scheme. For example:

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer <YOUR-API-KEY>'

For backward compatibility, the API also accepts an HTTP Basic header, which supports curl's -u flag (the API key is sent as the username with an empty password). New integrations should prefer the Bearer header shown above.

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances' \
  --header 'accept: application/json' \
  --user '<YOUR-API-KEY>:'

warning

Important

If you make a request without including a supported Authorization header, the request will fail.

Trying out the API

You can also try Lambda Cloud API endpoints directly from the API browser. To configure this feature:

1. Visit the API keys page in the Lambda Cloud dashboard.
2. Generate an API key, and then copy the key.
3. Paste your API key below, and then click Set key.

Set key

After you set the key, visit the Parameters & Request sample section of the endpoint you want to test, fill in the relevant parameters, and then click Send request to make a request. The response status and object will appear in the corresponding Response section.

Audit Events

Get audit events

GET/api/v1/audit-events

Retrieves a list of audit events that have occurred in your account. To view the full catalog of possible audit events, visit Access and security > Audit logs in the Lambda Cloud documentation.

Query Parameters

• startstringoptional

An ISO 8601 timestamp defining the start of the time range to query, inclusive. If omitted, the response starts at the earliest available event.

Format: date-time

• endstringoptional

An ISO 8601 timestamp defining the end of the time range to query, inclusive. If omitted, the response ends at the most recent event.

Format: date-time

• page_tokenstringoptional

The token returned by the previous API response to retrieve the next page of results.

• resource_typestringoptional

The resource type to filter by. By default, all available resource types are retrieved.

Response:200

• dataarray of AuditEventrequired[
  
  
  
  
  
  
  \
  • AuditEvent{
    
    
    
    
    
    
    
    Audit event in the account's audit log. To view the full catalog of
    possible audit events, visit
    Access and security > Audit logs
    in the Lambda Cloud documentation.
    
    
    
    
    
    
    \
    • service_namestringrequired
      
      
      
      
      
      
      
      The service in which the action was performed.\

- resource_namestringrequired







The type of resource that was affected.

- actionstringrequired







The action that was performed.

- catalog_versionstringrequired







The version of the event catalog schema.

- event_idstringrequired







The unique identifier (ID) for this audit event.

- event_timestringrequired







The UTC timestamp for when the event occurred (ISO 8601 format).

- actor_lrn(string | null)required







The Lambda Resource Name (LRN) of the actor who performed the action. This is the stable identifier for the actor; emails and display names can change or be reassigned over time.





Any ofCollapse

- string

- null


- actor_email(string | null)required







The email address of the actor, resolved at read time from the actor's identity. Reflects the current email, not the email at the time of the event. null for service identities (which have no email), system-generated events, and actors that no longer resolve to an identity in this account.





Any ofCollapse

- string

- null


- actor_display_name(string | null)required







A human-readable name for the actor, resolved at read time: the user's full name, or the display name of a service identity. null when unavailable or when the actor no longer resolves to an identity in this account.





Any ofCollapse

- string

- null


- resource_lrnsarray of stringrequired[







The Lambda Resource Names (LRNs) of the resources affected by this action.







- string


]

- resource_owner_lrn(string | null)required







The Lambda Resource Name (LRN) of the account that owns the affected resources.





Any ofCollapse

- string

- null


- request_api_key_lrn(string | null)required







The Lambda Resource Name (LRN) of the API key used to authenticate the request, if applicable.





Any ofCollapse

- string

- null


- client_ip(string | null)required







The IP address the request originated from. Shows lambda-internal for actions performed by Lambda staff. null for system-generated events and events recorded before this field was introduced.





Any ofCollapse

- string

- null


- client_user_agent(string | null)required







The User-Agent header supplied by the client that made the request. This value is client-controlled and informational only. null for system-generated events and events recorded before this field was introduced.





Any ofCollapse

- string

- null


- surface(string | null)required







The surface the request came through: console (logged-in browser session), api (API key), or system (generated by Lambda systems without a request). null when the surface could not be determined (for example, unauthenticated requests) and for events recorded before this field was introduced.





Any ofCollapse

- string

- null


- result(AuditResult | null)required







The result of the audited action, including its status and the HTTP status code when the action originated from an API request. null for events recorded before this field was introduced.





Any ofCollapse

- AuditResult{







The result of an audited action.







- statusenumrequired







The result of an audited action, open to future status values.






Possible values: - "success"
- "failure"

- status_code(integer | null)optional





Any ofCollapse

- integer

- null


}

- null


- additional_detailsobjectrequired{







Additional event-specific details. The exact keys returned vary by event type.







}


}

]

• page_token(string | null)required

Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

Any ofCollapse

• string

• null

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

start

end

page_token

resource_type

Reset params

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/audit-events' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "service_name": "cloud",\
      "resource_name": "api_key",\
      "action": "created",\
      "catalog_version": "2025-09-06",\
      "event_id": "0123456789abcdef0123456789abcdef",\
      "event_time": "2025-09-15T10:30:45.123456Z",\
      "actor_lrn": "lrn:cloud:identity:00112233445566778899aabbccddeeff",\
      "actor_email": "alice@example.com",\
      "actor_display_name": "Alice Example",\
      "resource_lrns": [\
        "lrn:cloud:api_key:ffeeddccbbaa99887766554433221100"\
      ],\
      "resource_owner_lrn": "lrn:cloud:account:fedcba9876543210fedcba9876543210",\
      "request_api_key_lrn": "lrn:cloud:api_key:0f1e2d3c4b5a69788796a5b4c3d2e1f0",\
      "client_ip": "203.0.113.42",\
      "client_user_agent": "curl/8.5.0",\
      "surface": "console",\
      "result": {\
        "status": "success",\
        "status_code": 200\
      },\
      "additional_details": {\
        "api_key_lrn": "lrn:cloud:api_key:ffeeddccbbaa99887766554433221100"\
      }\
    }\
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}

Live

Send a request to see the response.Send request

Filesystems

List filesystems

GET/api/v1/file-systems

Retrieves a list of your filesystems.

Parameters

There are no parameters for this endpoint.

Response:200

• dataarray of Filesystemrequired[
  
  
  
  
  
  
  \
  • Filesystem{
    
    
    
    
    
    
    
    Information about a shared filesystem.
    
    
    
    
    
    
    \
    • idstringrequired
      
      
      
      
      
      
      
      The unique identifier (ID) of the filesystem.\

- namestringrequired







The name of the filesystem.

- mount_pointstringrequired







The DEFAULT absolute path indicating where on instances the filesystem will be mounted.
If file_system_mounts were used at launch time, the actual mount point is in the
instance response.

- createdstringrequired







The date and time at which the filesystem was created. Formatted as an ISO 8601 timestamp.






Format: date-time

- created_byUserrequired{







The user in your Team that created the filesystem.







- idstringrequired







The unique identifier for the user.

- emailstringrequired







The email address of the user.

- statusenumrequired







The status of the user's account.






Possible values: - "active"
- "deactivated"

}

- is_in_usebooleanrequired







Whether the filesystem is currently mounted to an instance. Filesystems that
are mounted cannot be deleted.

- regionRegionrequired{







The region in which the filesystem is deployed.







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

- bytes_usedintegeroptional







The approximate amount of storage used by the filesystem in bytes. This estimate is
updated every few hours.


}

]

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/file-systems' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "id": "398578a2336b49079e74043f0bd2cfe8",\
      "name": "my-filesystem",\
      "mount_point": "/lambda/nfs/my-filesystem",\
      "created": "1970-01-01T00:00:00.000Z",\
      "created_by": {\
        "id": "3da5a70a57a7422ea8a7203f98b2198b",\
        "email": "me@example.com",\
        "status": "active"\
      },\
      "is_in_use": false,\
      "region": {\
        "name": "string",\
        "description": "string"\
      },\
      "bytes_used": 0\
    }\
  ]
}

Live

Send a request to see the response.Send request

Create filesystem

POST/api/v1/filesystems

Creates a new filesystem.

Body Parameters

• namestringrequired

The name of the filesystem.

• Minimum length: 1

  • Maximum length: 60
  • Regex pattern: ^[a-zA-Z]+[0-9a-zA-Z-]*$

• regionstringrequired

The region in which you want to create the filesystem.

Response:200

• dataFilesystemrequired{

Information about a shared filesystem.

• idstringrequired

The unique identifier (ID) of the filesystem.

• namestringrequired

The name of the filesystem.

• mount_pointstringrequired

The DEFAULT absolute path indicating where on instances the filesystem will be mounted. If file_system_mounts were used at launch time, the actual mount point is in the instance response.

• createdstringrequired

The date and time at which the filesystem was created. Formatted as an ISO 8601 timestamp.

Format: date-time

• created_byUserrequired{

The user in your Team that created the filesystem.

• idstringrequired

The unique identifier for the user.

• emailstringrequired

The email address of the user.

• statusenumrequired

The status of the user's account.

Possible values: - "active" - "deactivated"

}

• is_in_usebooleanrequired

Whether the filesystem is currently mounted to an instance. Filesystems that are mounted cannot be deleted.

• regionRegionrequired{

The region in which the filesystem is deployed.

• namestringrequired

The region code.

• descriptionstringrequired

The region description.

}

• bytes_usedintegeroptional

The approximate amount of storage used by the filesystem in bytes. This estimate is updated every few hours.

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/duplicate"
• "global/quota-exceeded"
• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"
• "global/invalid-address"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/filesystems' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "my-filesystem",
  "region": "us-west-1"
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "398578a2336b49079e74043f0bd2cfe8",
    "name": "my-filesystem",
    "mount_point": "/lambda/nfs/my-filesystem",
    "created": "1970-01-01T00:00:00.000Z",
    "created_by": {
      "id": "3da5a70a57a7422ea8a7203f98b2198b",
      "email": "me@example.com",
      "status": "active"
    },
    "is_in_use": false,
    "region": {
      "name": "string",
      "description": "string"
    },
    "bytes_used": 0
  }
}

Live

Send a request to see the response.Send request

Delete filesystem

DELETE/api/v1/filesystems/{id}

Deletes the filesystem with the specified ID. The filesystem must not be mounted to any running instances at the time of deletion.

Path Parameters

• idstringrequired

The unique identifier (ID) of the filesystem to delete

Response:200

• dataFilesystemDeleteResponserequired{

• deleted_idsarray of stringrequired[
  
  
  
  
  
  
  
  The unique identifiers of the filesystems that were deleted.
  
  
  
  
  
  
  \

  • string
    
    
    ]

}

Common Error Response Codes

400: Bad RequestCollapse

• "filesystems/filesystem-in-use"
• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

Parameters & Request sampleCollapse

id

Reset params

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/filesystems/398578a2336b49079e74043f0bd2cfe8' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "deleted_ids": [\
      "398578a2336b49079e74043f0bd2cfe8"\
    ]
  }
}

Live

Send a request to see the response.Send request

Firewalls

List inbound firewall rules

GET/api/v1/firewall-rules

Retrieves a list of your firewall rules.

Note: Firewall rules do not apply to the us-south-1 region.

Parameters

There are no parameters for this endpoint.

Response:200

• dataarray of FirewallRulerequired[
  
  
  
  
  
  
  \
  • FirewallRule{
    
    
    
    
    
    
    \
    • protocolenumrequired
      
      
      
      
      
      
      
      The protocol to which the rule applies.\

Possible values: - "tcp"
- "udp"
- "icmp"
- "all"

- port_rangearray of integeroptional[







An inclusive range of network ports specified as [min, max].
Not allowed for the icmp protocol but required for the others.



To specify a single port, list it twice (for example, [22,22]).





- Minimum items: 2
- Maximum items: 2

- integer





- Minimum : 1
- Maximum : 65535

]

- source_networkstringrequired







The set of source IPv4 addresses from which you want to allow inbound
traffic. These addresses must be specified in CIDR notation. You can
specify individual public IPv4 CIDR blocks such as 1.2.3.4 or
1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any
address.



This value is a string consisting of a public IPv4 address optionally
followed by a slash (/) and an integer mask (the network prefix).
If no mask is provided, the API assumes /32 by default.






Format: ipv4network

- descriptionstringrequired







A human-readable description of the rule.





- Minimum length: 0
- Maximum length: 128

}

]

Common Error Response Codes

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rules' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "protocol": "tcp",\
      "port_range": [\
        22,\
        22\
      ],\
      "source_network": "0.0.0.0/0",\
      "description": "Allow SSH from anywhere"\
    }\
  ]
}

Live

Send a request to see the response.Send request

Replace inbound firewall rules

PUT/api/v1/firewall-rules

Overwrites the inbound firewall rules currently active for your account's instances with the desired rules.

Note: Firewall rules do not apply to the us-south-1 region.

Body Parameters

• dataarray of FirewallRulerequired[
  
  
  
  
  
  
  
  The list of inbound firewall rules.
  
  
  
  
  
  
  \
  • FirewallRule{
    
    
    
    
    
    
    \
    • protocolenumrequired
      
      
      
      
      
      
      
      The protocol to which the rule applies.\

Possible values: - "tcp"
- "udp"
- "icmp"
- "all"

- port_rangearray of integeroptional[







An inclusive range of network ports specified as [min, max].
Not allowed for the icmp protocol but required for the others.



To specify a single port, list it twice (for example, [22,22]).





- Minimum items: 2
- Maximum items: 2

- integer





- Minimum : 1
- Maximum : 65535

]

- source_networkstringrequired







The set of source IPv4 addresses from which you want to allow inbound
traffic. These addresses must be specified in CIDR notation. You can
specify individual public IPv4 CIDR blocks such as 1.2.3.4 or
1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any
address.



This value is a string consisting of a public IPv4 address optionally
followed by a slash (/) and an integer mask (the network prefix).
If no mask is provided, the API assumes /32 by default.






Format: ipv4network

- descriptionstringrequired







A human-readable description of the rule.





- Minimum length: 0
- Maximum length: 128

}

]

Response:200

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request PUT --url 'https://cloud.lambda.ai/api/v1/firewall-rules' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "data": [\
    {\
      "protocol": "tcp",\
      "port_range": [\
        22,\
        22\
      ],\
      "source_network": "0.0.0.0/0",\
      "description": "Allow SSH from anywhere"\
    }\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "protocol": "tcp",\
      "port_range": [\
        22,\
        22\
      ],\
      "source_network": "0.0.0.0/0",\
      "description": "Allow SSH from anywhere"\
    }\
  ]
}

Live

Send a request to see the response.Send request

List firewall rulesets

GET/api/v1/firewall-rulesets

Retrieves a list of your firewall rulesets.

Parameters

There are no parameters for this endpoint.

Response:200

• dataarray of FirewallRulesetrequired[
  
  
  
  
  
  
  \
  • FirewallRuleset{
    
    
    
    
    
    
    
    A collection of firewall rules that can be associated with instances.
    
    
    
    
    
    
    \
    • idstringrequired
      
      
      
      
      
      
      
      The unique identifier of the firewall ruleset.\

- namestringrequired







The name of the firewall ruleset.

- regionRegionrequired{







The region in which the firewall ruleset is deployed.







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

- rulesarray of FirewallRulerequired[







The list of firewall rules in this ruleset.







- FirewallRule{







- protocolenumrequired







The protocol to which the rule applies.






Possible values: - "tcp"
- "udp"
- "icmp"
- "all"

- port_rangearray of integeroptional[







An inclusive range of network ports specified as [min, max].
Not allowed for the icmp protocol but required for the others.



To specify a single port, list it twice (for example, [22,22]).





- Minimum items: 2
- Maximum items: 2

- integer





- Minimum : 1
- Maximum : 65535

]

- source_networkstringrequired







The set of source IPv4 addresses from which you want to allow inbound
traffic. These addresses must be specified in CIDR notation. You can
specify individual public IPv4 CIDR blocks such as 1.2.3.4 or
1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any
address.



This value is a string consisting of a public IPv4 address optionally
followed by a slash (/) and an integer mask (the network prefix).
If no mask is provided, the API assumes /32 by default.






Format: ipv4network

- descriptionstringrequired







A human-readable description of the rule.





- Minimum length: 0
- Maximum length: 128

}

]

- createdstringrequired







The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.






Format: date-time

- instance_idsarray of stringrequired[







The IDs of instances this firewall ruleset is associated with.







- string


]

}

]

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "id": "c4d291f47f9d436fa39f58493ce3b50d",\
      "name": "My Firewall Ruleset",\
      "region": {\
        "name": "string",\
        "description": "string"\
      },\
      "rules": [\
        {\
          "protocol": "tcp",\
          "port_range": [\
            22,\
            22\
          ],\
          "source_network": "0.0.0.0/0",\
          "description": "Allow SSH from anywhere"\
        }\
      ],\
      "created": "1970-01-01T00:00:00.000Z",\
      "instance_ids": [\
        "string"\
      ]\
    }\
  ]
}

Live

Send a request to see the response.Send request

Create firewall ruleset

POST/api/v1/firewall-rulesets

Creates a new firewall ruleset with the specified name and rules.

Body Parameters

• namestringrequired

The name of the firewall ruleset.

• Maximum length: 64

• regionstringrequired

The region in which the firewall ruleset is deployed.

• rulesarray of FirewallRulerequired[
  
  
  
  
  
  
  
  The firewall rules to include in the ruleset.
  
  
  
  
  
  
  \
  • FirewallRule{
    
    
    
    
    
    
    \
    • protocolenumrequired
      
      
      
      
      
      
      
      The protocol to which the rule applies.\

Possible values: - "tcp"
- "udp"
- "icmp"
- "all"

- port_rangearray of integeroptional[







An inclusive range of network ports specified as [min, max].
Not allowed for the icmp protocol but required for the others.



To specify a single port, list it twice (for example, [22,22]).





- Minimum items: 2
- Maximum items: 2

- integer





- Minimum : 1
- Maximum : 65535

]

- source_networkstringrequired







The set of source IPv4 addresses from which you want to allow inbound
traffic. These addresses must be specified in CIDR notation. You can
specify individual public IPv4 CIDR blocks such as 1.2.3.4 or
1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any
address.



This value is a string consisting of a public IPv4 address optionally
followed by a slash (/) and an integer mask (the network prefix).
If no mask is provided, the API assumes /32 by default.






Format: ipv4network

- descriptionstringrequired







A human-readable description of the rule.





- Minimum length: 0
- Maximum length: 128

}

]

Response:200

• dataFirewallRulesetrequired{

A collection of firewall rules that can be associated with instances.

• idstringrequired

The unique identifier of the firewall ruleset.

• namestringrequired

The name of the firewall ruleset.

• regionRegionrequired{

The region in which the firewall ruleset is deployed.

• namestringrequired

The region code.

• descriptionstringrequired

The region description.

}

• rulesarray of FirewallRulerequired[
  
  
  
  
  
  
  
  The list of firewall rules in this ruleset.
  
  
  
  
  
  
  \
  • FirewallRule{
    
    
    
    
    
    
    \
    • protocolenumrequired\

The protocol to which the rule applies.






Possible values: - "tcp"
- "udp"
- "icmp"
- "all"

- port_rangearray of integeroptional[







An inclusive range of network ports specified as [min, max].
Not allowed for the icmp protocol but required for the others.



To specify a single port, list it twice (for example, [22,22]).





- Minimum items: 2
- Maximum items: 2

- integer





- Minimum : 1
- Maximum : 65535

]

- source_networkstringrequired







The set of source IPv4 addresses from which you want to allow inbound
traffic. These addresses must be specified in CIDR notation. You can
specify individual public IPv4 CIDR blocks such as 1.2.3.4 or
1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any
address.



This value is a string consisting of a public IPv4 address optionally
followed by a slash (/) and an integer mask (the network prefix).
If no mask is provided, the API assumes /32 by default.






Format: ipv4network

- descriptionstringrequired







A human-readable description of the rule.





- Minimum length: 0
- Maximum length: 128

}

]

• createdstringrequired

The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

Format: date-time

• instance_idsarray of stringrequired[
  
  
  
  
  
  
  
  The IDs of instances this firewall ruleset is associated with.
  
  
  
  
  
  
  \
  • string
    
    
    ]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/quota-exceeded"
• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

409: ConflictCollapse

• "global/internal-error"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Firewall Ruleset",
  "region": "string",
  "rules": [\
    {\
      "protocol": "tcp",\
      "port_range": [\
        22,\
        22\
      ],\
      "source_network": "0.0.0.0/0",\
      "description": "Allow SSH from anywhere"\
    }\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Firewall Ruleset",
    "region": {
      "name": "string",
      "description": "string"
    },
    "rules": [\
      {\
        "protocol": "tcp",\
        "port_range": [\
          22,\
          22\
        ],\
        "source_network": "0.0.0.0/0",\
        "description": "Allow SSH from anywhere"\
      }\
    ],
    "created": "1970-01-01T00:00:00.000Z",
    "instance_ids": [\
      "string"\
    ]
  }
}

Live

Send a request to see the response.Send request

Retrieve global firewall ruleset details

GET/api/v1/firewall-rulesets/global

Retrieves the details of the global firewall ruleset.

Parameters

There are no parameters for this endpoint.

Response:200

• dataGlobalFirewallRulesetrequired{

Firewall rules that apply across all regions.

• idstringrequired

The unique identifier of the firewall ruleset.

• Const:

• namestringrequired

The name of the firewall ruleset.

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/global' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "global",
    "name": "Default Workspace Global Rules",
    "rules": [\
      {\
        "protocol": "tcp",\
        "port_range": [\
          22,\
          22\
        ],\
        "source_network": "0.0.0.0/0",\
        "description": "Allow SSH from anywhere"\
      }\
    ]
  }
}

Live

Send a request to see the response.Send request

Update global firewall ruleset

PATCH/api/v1/firewall-rulesets/global

Updates the global firewall ruleset. This allows updating the rules only.

Body Parameters

• rulesarray of FirewallRuleoptional[
  
  
  
  
  
  
  
  The new firewall rules for the ruleset. If not provided, the rules will not be updated.
  
  
  
  
  
  
  \
  • FirewallRule{
    
    
    
    
    
    
    \
    • protocolenumrequired
      
      
      
      
      
      
      
      The protocol to which the rule applies.\

Possible values: - "tcp"
- "udp"
- "icmp"
- "all"

- port_rangearray of integeroptional[







An inclusive range of network ports specified as [min, max].
Not allowed for the icmp protocol but required for the others.



To specify a single port, list it twice (for example, [22,22]).





- Minimum items: 2
- Maximum items: 2

- integer





- Minimum : 1
- Maximum : 65535

]

- source_networkstringrequired







The set of source IPv4 addresses from which you want to allow inbound
traffic. These addresses must be specified in CIDR notation. You can
specify individual public IPv4 CIDR blocks such as 1.2.3.4 or
1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any
address.



This value is a string consisting of a public IPv4 address optionally
followed by a slash (/) and an integer mask (the network prefix).
If no mask is provided, the API assumes /32 by default.






Format: ipv4network

- descriptionstringrequired







A human-readable description of the rule.





- Minimum length: 0
- Maximum length: 128

}

]

Response:200

• dataGlobalFirewallRulesetrequired{

Firewall rules that apply across all regions.

• idstringrequired

The unique identifier of the firewall ruleset.

• Const:

• namestringrequired

The name of the firewall ruleset.

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

409: ConflictCollapse

• "global/internal-error"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/global' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "rules": [\
    {\
      "protocol": "tcp",\
      "port_range": [\
        22,\
        22\
      ],\
      "source_network": "0.0.0.0/0",\
      "description": "Allow SSH from anywhere"\
    }\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

Live

Send a request to see the response.Send request

Retrieve firewall ruleset details

GET/api/v1/firewall-rulesets/{id}

Retrieves the details of a specific firewall ruleset.

Path Parameters

• idstringrequired

The unique identifier (ID) of the firewall ruleset

Response:200

• dataFirewallRulesetrequired{

A collection of firewall rules that can be associated with instances.

• idstringrequired

The unique identifier of the firewall ruleset.

• namestringrequired

The name of the firewall ruleset.

• regionRegionrequired{

The region in which the firewall ruleset is deployed.

• namestringrequired

The region code.

• descriptionstringrequired

The region description.

}

• createdstringrequired

The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

Format: date-time

• instance_idsarray of stringrequired[
  
  
  
  
  
  
  
  The IDs of instances this firewall ruleset is associated with.
  
  
  
  
  
  
  \
  • string
    
    
    ]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

Parameters & Request sampleCollapse

id

Reset params

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/c4d291f47f9d436fa39f58493ce3b50d' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

Live

Send a request to see the response.Send request

Update firewall ruleset

PATCH/api/v1/firewall-rulesets/{id}

Updates a firewall ruleset. This is a partial update that allows updating either the name, rules, or both.

Path Parameters

• idstringrequired

The unique identifier (ID) of the firewall ruleset

Body Parameters

• namestringoptional

The new name for the firewall ruleset. If not provided, the name will not be updated.

• Maximum length: 64

Response:200

• dataFirewallRulesetrequired{

A collection of firewall rules that can be associated with instances.

• idstringrequired

The unique identifier of the firewall ruleset.

• namestringrequired

The name of the firewall ruleset.

• regionRegionrequired{

The region in which the firewall ruleset is deployed.

• namestringrequired

The region code.

• descriptionstringrequired

The region description.

}

• createdstringrequired

The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

Format: date-time

• instance_idsarray of stringrequired[
  
  
  
  
  
  
  
  The IDs of instances this firewall ruleset is associated with.
  
  
  
  
  
  
  \
  • string
    
    
    ]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

409: ConflictCollapse

• "global/internal-error"

Parameters & Request sampleCollapse

id

Request body

Reset params

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/c4d291f47f9d436fa39f58493ce3b50d' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Updated Firewall Ruleset",
  "rules": [\
    {\
      "protocol": "tcp",\
      "port_range": [\
        22,\
        22\
      ],\
      "source_network": "0.0.0.0/0",\
      "description": "Allow SSH from anywhere"\
    }\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

Live

Send a request to see the response.Send request

Delete firewall ruleset

DELETE/api/v1/firewall-rulesets/{id}

Deletes the firewall ruleset with the specified ID.

Path Parameters

• idstringrequired

The unique identifier (ID) of the firewall ruleset

Response:200

• dataEmptyResponserequired{

}

Common Error Response Codes

400: Bad RequestCollapse

• "firewall-rulesets/firewall-ruleset-in-use"
• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

409: ConflictCollapse

• "global/internal-error"

Parameters & Request sampleCollapse

id

Reset params

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/c4d291f47f9d436fa39f58493ce3b50d' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {}
}

Live

Send a request to see the response.Send request

Images

List available images

GET/api/v1/images

Retrieves a list of available images by region.

Parameters

There are no parameters for this endpoint.

Response:200

• dataarray of Imagerequired[
  
  
  
  
  
  
  \
  • Image{
    
    
    
    
    
    
    
    An available machine image in Lambda Cloud.
    
    
    
    
    
    
    \
    • idstringrequired
      
      
      
      
      
      
      
      The unique identifier (ID) for an image.\

- created_timestringrequired







The date and time that the image was created.






Format: date-time

- updated_timestringrequired







The date and time that the image was last updated.






Format: date-time

- namestringrequired







The human-readable identifier for an image.

- descriptionstringrequired







Additional information about the image.

- familystringrequired







The family the image belongs to.

- versionstringrequired







The image version.

- architectureenumrequired







The CPU architecture the image supports.






Possible values: - "x86_64"
- "arm64"

- regionRegionrequired{







The region in which this image is available.







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

}

]

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/images' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "id": "43336648-096d-4cba-9aa2-f9bb7727639d",\
      "created_time": "1970-01-01T00:00:00.000Z",\
      "updated_time": "1970-01-01T00:00:00.000Z",\
      "name": "ubuntu-24.04.01",\
      "description": "Ubuntu LTS",\
      "family": "ubuntu-lts",\
      "version": "24.04.01",\
      "architecture": "x86_64",\
      "region": {\
        "name": "string",\
        "description": "string"\
      }\
    }\
  ]
}

Live

Send a request to see the response.Send request

Instances

Launch instances

POST/api/v1/instance-operations/launch

Launches a Lambda On-Demand Cloud instance.

Body Parameters

• region_namestringrequired

The region into which you want to launch the instance.

• instance_type_namestringrequired

The type of instance you want to launch. To retrieve a list of available instance types, see List available instance types.

• ssh_key_namesarray of stringrequired[
  
  
  
  
  
  
  
  The names of the SSH keys you want to use to provide access to the instance.
  Currently, exactly one SSH key must be specified.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• file_system_namesarray of stringoptional[
  
  
  
  
  
  
  
  The names of the filesystems you want to mount to the instance. When specified
  alongside file_system_mounts, any filesystems referred to in both lists will use the
  mount path specified in file_system_mounts, rather than the default.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• file_system_mountsarray of RequestedFilesystemMountEntryoptional[
  
  
  
  
  
  
  
  The filesystem mounts to mount to the instance. When specified alongside
  file_system_names, any filesystems referred to in both lists will use the
  mount path specified in file_system_mounts, rather than the default.
  
  
  
  
  
  
  \

  • RequestedFilesystemMountEntry{
    
    
    
    
    
    
    
    The mount point for a filesystem mounted to an instance.
    
    
    
    
    
    
    \
    • mount_pointstringrequired
      
      
      
      
      
      
      
      The absolute path indicating where on the instance the filesystem will be mounted.\

- Maximum length: 256
- Regex pattern: ^(/home|/lambda/nfs|/data)[//a-zA-Z0-9-]*$

- file_system_idstringrequired







The id of the filesystem to mount to the instance.


}

]

• hostnamestringoptional

The hostname to assign to the instance. If not specified, a default, IP-address-based hostname is assigned. This hostname is driven into /etc/hostname on the instance.

• Minimum length: 1

  • Maximum length: 63
  • Regex pattern: ^[a-z0-9][0-9a-z-]{0,62}$

• namestringoptional

The name you want to assign to your instance. Must be 64 characters or fewer.

• Minimum length: 0

  • Maximum length: 64

• image(ImageSpecificationID | ImageSpecificationFamily)optional

The machine image you want to use. Defaults to the latest Lambda Stack image.

Any ofCollapse

• ImageSpecificationID{

Specifies the image to use by its unique identifier.

• idstringrequired

}

• ImageSpecificationFamily{

Specifies the image to use by its family name.

• familystringrequired

The family name of the image.

}

• user_datastringoptional

An instance configuration string specified in a valid cloud-init user-data format. You can use this field to configure your instance on launch. The user data string must be plain text and cannot exceed 1MB in size.

Format: password

• tagsarray of RequestedTagEntryoptional[
  
  
  
  
  
  
  
  Key/value pairs representing the instance's tags.
  
  
  
  
  
  
  \
  • RequestedTagEntry{
    
    
    
    
    
    
    \
    • keystringrequired
      
      
      
      
      
      
      
      The key of the tag.\

- Maximum length: 55
- Regex pattern: ^[a-z][a-z0-9-:]+$

- valuestringrequired







The value of the tag.





- Maximum length: 128

}

]

• firewall_rulesetsarray of FirewallRulesetEntryoptional[
  
  
  
  
  
  
  
  The firewall rulesets to associate with the instance.
  The firewall rulesets must exist in the same region as the instance.
  
  
  
  
  
  
  \
  • FirewallRulesetEntry{
    
    
    
    
    
    
    
    Reference to a firewall ruleset.
    
    
    
    
    
    
    \
    • idstringrequired
      
      
      
      
      
      
      
      The unique identifier of the firewall ruleset.\

}

]

Response:200

• dataInstanceLaunchResponserequired{

• instance_idsarray of stringrequired[
  
  
  
  
  
  
  
  The unique identifiers (IDs) of the launched instances.
  
  
  
  
  
  
  \

  • string
    
    
    ]

}

Common Error Response Codes

400: Bad RequestCollapse

• "instance-operations/launch/file-system-in-wrong-region"
• "instance-operations/launch/insufficient-capacity"
• "global/invalid-parameters"
• "global/object-does-not-exist"
• "global/quota-exceeded"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"
• "global/invalid-address"

404: Not FoundCollapse

• "global/object-does-not-exist"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instance-operations/launch' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "region_name": "string",
  "instance_type_name": "gpu_8x_a100",
  "ssh_key_names": [\
    "my-public-key"\
  ],
  "file_system_names": [\
    "my-filesystem"\
  ],
  "file_system_mounts": [\
    {\
      "mount_point": "/data/custom-mount-point",\
      "file_system_id": "398578a2336b49079e74043f0bd2cfe8"\
    }\
  ],
  "hostname": "headnode1",
  "name": "My Instance",
  "image": {
    "id": "ddaedf1b7a0e41ac981711504493b242"
  },
  "user_data": "#cloud-config\nruncmd:\n  - echo \"Hello, World\" > /tmp/hello.txt\n",
  "tags": [\
    {\
      "key": "key1",\
      "value": "value1"\
    }\
  ],
  "firewall_rulesets": [\
    {\
      "id": "c4d291f47f9d436fa39f58493ce3b50d"\
    }\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "instance_ids": [\
      "0920582c7ff041399e34823a0be62549"\
    ]
  }
}

Live

Send a request to see the response.Send request

Restart instances

POST/api/v1/instance-operations/restart

Restarts one or more instances.

Body Parameters

• instance_idsarray of stringrequired[
  
  
  
  
  
  
  
  The unique identifiers (IDs) of the instances to restart.
  
  
  
  
  
  
  \
  • string
    
    
    ]

Response:200

• dataInstanceRestartResponserequired{

• restarted_instancesarray of Instancerequired[
  
  
  
  
  
  
  
  The list of instances that were successfully restarted.
  
  
  
  
  
  
  \

  • Instance{
    
    
    
    
    
    
    
    Detailed information about the instance.\

- idstringrequired







The unique identifier of the instance.

- namestringoptional







If set, the user-provided name of the instance.





- Minimum length: 0
- Maximum length: 64

- ipstringoptional







The public IPv4 address of the instance.

- private_ipstringoptional







The private IPv4 address of the instance.

- statusenumrequired







The current status of the instance.






Possible values: - "booting"
- "active"
- "unhealthy"
- "terminated"
- "terminating"
- "preempted"

- ssh_key_namesarray of stringrequired[







The names of the SSH keys that are allowed to access the instance.







- string


]

- file_system_namesarray of stringrequired[







The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.







- string


]

- file_system_mountsarray of FilesystemMountEntryoptional[







The filesystems, along with the mount paths, mounted to
the instances. If no filesystems are mounted, this parameter
will be missing from the response.







- FilesystemMountEntry{







The mount point for a filesystem mounted to an instance.







- mount_pointstringrequired







The absolute path indicating where on the instance the filesystem will be mounted.

- file_system_idstringrequired







The id of the filesystem to mount to the instance.


}

]

- regionRegionrequired{







The region in which the instance is deployed.







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

- instance_typeInstanceTyperequired{







Detailed information about the instance's instance type.







- namestringrequired







The name of the instance type.

- descriptionstringrequired







A description of the instance type.

- gpu_descriptionstringrequired







The type of GPU used by this instance type.

- price_cents_per_hourintegerrequired







The price of the instance type in US cents per hour.

- specsInstanceTypeSpecsrequired{







Detailed technical specifications for the instance type.







- vcpusintegerrequired







The number of virtual CPUs.

- memory_gibintegerrequired







The amount of RAM in gibibytes (GiB).

- storage_gibintegerrequired







The amount of storage in gibibytes (GiB).

- gpusintegerrequired







The number of GPUs.


}

- architectureenumrequired







The CPU architecture of the instance type.






Possible values: - "x86_64"
- "arm64"

}

- hostnamestringoptional







The hostname assigned to this instance, which resolves to the instance's IP.

- jupyter_tokenstringoptional







The secret token used to log into the JupyterLab server hosted on the instance.

- jupyter_urlstringoptional







The URL that opens the JupyterLab environment on the instance.

- actionsInstanceActionAvailabilityrequired{







A set of status objects representing the current availability of common instance operations.







- migrateInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be migrated.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- rebuildInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be rebuilt.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- restartInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be restarted.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- cold_rebootInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently eligible for a cold reboot.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- terminateInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be terminated.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

}

- tagsarray of TagEntryoptional[







Key/value pairs representing the instance's tags.







- TagEntry{







- keystringrequired







The key of the tag.

- valuestringrequired







The value of the tag.


}

]

- firewall_rulesetsarray of FirewallRulesetEntryoptional[







The firewall rulesets associated with this instance.







- FirewallRulesetEntry{







Reference to a firewall ruleset.







- idstringrequired







The unique identifier of the firewall ruleset.


}

]

}

]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

409: ConflictCollapse

• "global/conflict"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instance-operations/restart' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "instance_ids": [\
    "0920582c7ff041399e34823a0be62549"\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "restarted_instances": [\
      {\
        "id": "0920582c7ff041399e34823a0be62549",\
        "name": "My Instance",\
        "ip": "198.51.100.2",\
        "private_ip": "10.0.2.100",\
        "status": "active",\
        "ssh_key_names": [\
          "My SSH key"\
        ],\
        "file_system_names": [\
          "my-filesystem"\
        ],\
        "file_system_mounts": [\
          {\
            "mount_point": "/lambda/nfs/my-filesystem",\
            "file_system_id": "a098b0c7ff041399e34823a0be62549"\
          }\
        ],\
        "region": {\
          "name": "us-west-1",\
          "description": "California, USA"\
        },\
        "instance_type": {\
          "name": "gpu_8x_example",\
          "description": "8x Example GPU (40 GB SXM4)",\
          "gpu_description": "Example GPU (40 GB SXM4)",\
          "price_cents_per_hour": 1592,\
          "specs": {\
            "vcpus": 124,\
            "memory_gib": 1800,\
            "storage_gib": 6144,\
            "gpus": 8\
          },\
          "architecture": "x86_64"\
        },\
        "hostname": "198.51.100.2",\
        "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",\
        "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",\
        "is_reserved": false,\
        "actions": {\
          "migrate": {\
            "available": true\
          },\
          "rebuild": {\
            "available": true\
          },\
          "restart": {\
            "available": true\
          },\
          "cold_reboot": {\
            "available": true\
          },\
          "terminate": {\
            "available": true\
          }\
        },\
        "tags": [\
          {\
            "key": "key1",\
            "value": "value1"\
          },\
          {\
            "key": "key2",\
            "value": "value2"\
          }\
        ]\
      }\
    ]
  }
}

Live

Send a request to see the response.Send request

Terminate instances

POST/api/v1/instance-operations/terminate

Terminates one or more instances.

Body Parameters

• instance_idsarray of stringrequired[
  
  
  
  
  
  
  
  The unique identifiers (IDs) of the instances to terminate.
  
  
  
  
  
  
  \
  • string
    
    
    ]

Response:200

• dataInstanceTerminateResponserequired{

• terminated_instancesarray of Instancerequired[
  
  
  
  
  
  
  
  The list of instances that were successfully terminated.
  
  
  
  
  
  
  \

  • Instance{
    
    
    
    
    
    
    
    Detailed information about the instance.\

- idstringrequired







The unique identifier of the instance.

- namestringoptional







If set, the user-provided name of the instance.





- Minimum length: 0
- Maximum length: 64

- ipstringoptional







The public IPv4 address of the instance.

- private_ipstringoptional







The private IPv4 address of the instance.

- statusenumrequired







The current status of the instance.






Possible values: - "booting"
- "active"
- "unhealthy"
- "terminated"
- "terminating"
- "preempted"

- ssh_key_namesarray of stringrequired[







The names of the SSH keys that are allowed to access the instance.







- string


]

- file_system_namesarray of stringrequired[







The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.







- string


]

- file_system_mountsarray of FilesystemMountEntryoptional[







The filesystems, along with the mount paths, mounted to
the instances. If no filesystems are mounted, this parameter
will be missing from the response.







- FilesystemMountEntry{







The mount point for a filesystem mounted to an instance.







- mount_pointstringrequired







The absolute path indicating where on the instance the filesystem will be mounted.

- file_system_idstringrequired







The id of the filesystem to mount to the instance.


}

]

- regionRegionrequired{







The region in which the instance is deployed.







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

- instance_typeInstanceTyperequired{







Detailed information about the instance's instance type.







- namestringrequired







The name of the instance type.

- descriptionstringrequired







A description of the instance type.

- gpu_descriptionstringrequired







The type of GPU used by this instance type.

- price_cents_per_hourintegerrequired







The price of the instance type in US cents per hour.

- specsInstanceTypeSpecsrequired{







Detailed technical specifications for the instance type.







- vcpusintegerrequired







The number of virtual CPUs.

- memory_gibintegerrequired







The amount of RAM in gibibytes (GiB).

- storage_gibintegerrequired







The amount of storage in gibibytes (GiB).

- gpusintegerrequired







The number of GPUs.


}

- architectureenumrequired







The CPU architecture of the instance type.






Possible values: - "x86_64"
- "arm64"

}

- hostnamestringoptional







The hostname assigned to this instance, which resolves to the instance's IP.

- jupyter_tokenstringoptional







The secret token used to log into the JupyterLab server hosted on the instance.

- jupyter_urlstringoptional







The URL that opens the JupyterLab environment on the instance.

- actionsInstanceActionAvailabilityrequired{







A set of status objects representing the current availability of common instance operations.







- migrateInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be migrated.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- rebuildInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be rebuilt.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- restartInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be restarted.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- cold_rebootInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently eligible for a cold reboot.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- terminateInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be terminated.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

}

- tagsarray of TagEntryoptional[







Key/value pairs representing the instance's tags.







- TagEntry{







- keystringrequired







The key of the tag.

- valuestringrequired







The value of the tag.


}

]

- firewall_rulesetsarray of FirewallRulesetEntryoptional[







The firewall rulesets associated with this instance.







- FirewallRulesetEntry{







Reference to a firewall ruleset.







- idstringrequired







The unique identifier of the firewall ruleset.


}

]

}

]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instance-operations/terminate' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "instance_ids": [\
    "0920582c7ff041399e34823a0be62549"\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "terminated_instances": [\
      {\
        "id": "0920582c7ff041399e34823a0be62549",\
        "name": "My Instance",\
        "ip": "198.51.100.2",\
        "private_ip": "10.0.2.100",\
        "status": "terminating",\
        "ssh_key_names": [\
          "My SSH key"\
        ],\
        "file_system_names": [\
          "my-filesystem"\
        ],\
        "file_system_mounts": [\
          {\
            "mount_point": "/lambda/nfs/my-filesystem",\
            "file_system_id": "a098b0c7ff041399e34823a0be62549"\
          }\
        ],\
        "region": {\
          "name": "us-west-1",\
          "description": "California, USA"\
        },\
        "instance_type": {\
          "name": "gpu_8x_example",\
          "description": "8x Example GPU (40 GB SXM4)",\
          "gpu_description": "Example GPU (40 GB SXM4)",\
          "price_cents_per_hour": 1592,\
          "specs": {\
            "vcpus": 124,\
            "memory_gib": 1800,\
            "storage_gib": 6144,\
            "gpus": 8\
          },\
          "architecture": "x86_64"\
        },\
        "hostname": "198.51.100.2",\
        "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",\
        "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",\
        "is_reserved": false,\
        "actions": {\
          "migrate": {\
            "available": true\
          },\
          "rebuild": {\
            "available": true\
          },\
          "restart": {\
            "available": true\
          },\
          "cold_reboot": {\
            "available": true\
          },\
          "terminate": {\
            "available": true\
          }\
        },\
        "tags": [\
          {\
            "key": "key1",\
            "value": "value1"\
          },\
          {\
            "key": "key2",\
            "value": "value2"\
          }\
        ]\
      }\
    ]
  }
}

Live

Send a request to see the response.Send request

List available instance types

GET/api/v1/instance-types

Retrieves a list of the instance types currently offered on Lambda's public cloud, as well as details about each type. Details include resource specifications, pricing, and regional availability.

Parameters

There are no parameters for this endpoint.

Response:200

• dataInstanceTypesrequired

• InstanceTypesItemoptional{

Detailed information and regional availability for the instance type.

• instance_typeInstanceTyperequired{

The description, technical specifications, and metadata for this instance type.

• namestringrequired

The name of the instance type.

• descriptionstringrequired

A description of the instance type.

• gpu_descriptionstringrequired

The type of GPU used by this instance type.

• price_cents_per_hourintegerrequired

The price of the instance type in US cents per hour.

• specsInstanceTypeSpecsrequired{

Detailed technical specifications for the instance type.

• vcpusintegerrequired

The number of virtual CPUs.

• memory_gibintegerrequired

The amount of RAM in gibibytes (GiB).

• storage_gibintegerrequired

The amount of storage in gibibytes (GiB).

• gpusintegerrequired

The number of GPUs.

}

• architectureenumrequired

The CPU architecture of the instance type.

Possible values: - "x86_64" - "arm64"

}

• regions_with_capacity_availablearray of Regionrequired[
  
  
  
  
  
  
  
  A list of the regions in which this instance type is available.\

- Region{







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instance-types' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "gpu_8x_example": {
      "instance_type": {
        "name": "gpu_8x_example",
        "description": "8x Example GPU (40 GB SXM4)",
        "gpu_description": "Example GPU (40 GB SXM4)",
        "price_cents_per_hour": 1592,
        "specs": {
          "vcpus": 124,
          "memory_gib": 1800,
          "storage_gib": 6144,
          "gpus": 8
        },
        "architecture": "x86_64"
      },
      "regions_with_capacity_available": [\
        {\
          "name": "us-west-1",\
          "description": "California, USA"\
        }\
      ]
    }
  }
}

Live

Send a request to see the response.Send request

List running instances

GET/api/v1/instances

Retrieves a list of your running instances.

Query Parameters

• cluster_idstringoptional

If provided, the resulting list will only include instances that are part of a cluster with this unique identifier (ID).

Response:200

• dataarray of Instancerequired[
  
  
  
  
  
  
  \
  • Instance{
    
    
    
    
    
    
    
    Detailed information about the instance.
    
    
    
    
    
    
    \
    • idstringrequired
      
      
      
      
      
      
      
      The unique identifier of the instance.\

- namestringoptional







If set, the user-provided name of the instance.





- Minimum length: 0
- Maximum length: 64

- ipstringoptional







The public IPv4 address of the instance.

- private_ipstringoptional







The private IPv4 address of the instance.

- statusenumrequired







The current status of the instance.






Possible values: - "booting"
- "active"
- "unhealthy"
- "terminated"
- "terminating"
- "preempted"

- ssh_key_namesarray of stringrequired[







The names of the SSH keys that are allowed to access the instance.







- string


]

- file_system_namesarray of stringrequired[







The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.







- string


]

- file_system_mountsarray of FilesystemMountEntryoptional[







The filesystems, along with the mount paths, mounted to
the instances. If no filesystems are mounted, this parameter
will be missing from the response.







- FilesystemMountEntry{







The mount point for a filesystem mounted to an instance.







- mount_pointstringrequired







The absolute path indicating where on the instance the filesystem will be mounted.

- file_system_idstringrequired







The id of the filesystem to mount to the instance.


}

]

- regionRegionrequired{







The region in which the instance is deployed.







- namestringrequired







The region code.

- descriptionstringrequired







The region description.


}

- instance_typeInstanceTyperequired{







Detailed information about the instance's instance type.







- namestringrequired







The name of the instance type.

- descriptionstringrequired







A description of the instance type.

- gpu_descriptionstringrequired







The type of GPU used by this instance type.

- price_cents_per_hourintegerrequired







The price of the instance type in US cents per hour.

- specsInstanceTypeSpecsrequired{







Detailed technical specifications for the instance type.







- vcpusintegerrequired







The number of virtual CPUs.

- memory_gibintegerrequired







The amount of RAM in gibibytes (GiB).

- storage_gibintegerrequired







The amount of storage in gibibytes (GiB).

- gpusintegerrequired







The number of GPUs.


}

- architectureenumrequired







The CPU architecture of the instance type.






Possible values: - "x86_64"
- "arm64"

}

- hostnamestringoptional







The hostname assigned to this instance, which resolves to the instance's IP.

- jupyter_tokenstringoptional







The secret token used to log into the JupyterLab server hosted on the instance.

- jupyter_urlstringoptional







The URL that opens the JupyterLab environment on the instance.

- actionsInstanceActionAvailabilityrequired{







A set of status objects representing the current availability of common instance operations.







- migrateInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be migrated.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- rebuildInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be rebuilt.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- restartInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be restarted.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- cold_rebootInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently eligible for a cold reboot.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

- terminateInstanceActionAvailabilityDetailsrequired{







Indicates whether the instance is currently able to be terminated.
If not, describes why the operation is blocked.







- availablebooleanrequired







If set, indicates that the relevant operation can be performed on the instance in its current state.

- reason_code(enum | string)optional







A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.





Any ofCollapse

- enum






Possible values: - "vm-has-not-launched"
- "vm-is-too-old"
- "vm-is-terminating"
- "vm-action-in-progress"
- "vm-action-unavailable-bare-metal"

- string


- reason_descriptionstringoptional







A longer description of why this operation is currently blocked. Only provided if the operation is blocked.


}

}

- tagsarray of TagEntryoptional[







Key/value pairs representing the instance's tags.







- TagEntry{







- keystringrequired







The key of the tag.

- valuestringrequired







The value of the tag.


}

]

- firewall_rulesetsarray of FirewallRulesetEntryoptional[







The firewall rulesets associated with this instance.







- FirewallRulesetEntry{







Reference to a firewall ruleset.







- idstringrequired







The unique identifier of the firewall ruleset.


}

]

}

]

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"
• "global/forbidden"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

cluster_id

Reset params

Request sample

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "id": "0920582c7ff041399e34823a0be62549",\
      "name": "My Instance",\
      "ip": "198.51.100.2",\
      "private_ip": "10.0.2.100",\
      "status": "booting",\
      "ssh_key_names": [\
        "My SSH key"\
      ],\
      "file_system_names": [\
        "my-filesystem"\
      ],\
      "file_system_mounts": [\
        {\
          "mount_point": "/data/custom-mount-point",\
          "file_system_id": "398578a2336b49079e74043f0bd2cfe8"\
        }\
      ],\
      "region": {\
        "name": "string",\
        "description": "string"\
      },\
      "instance_type": {\
        "name": "gpu_8x_h100_sxm5gdr",\
        "description": "8x H100 (80 GB SXM5)",\
        "gpu_description": "H100 (80 GB SXM5)",\
        "price_cents_per_hour": 3592,\
        "specs": {\
          "vcpus": 208,\
          "memory_gib": 1800,\
          "storage_gib": 24780,\
          "gpus": 8\
        },\
        "architecture": "x86_64"\
      },\
      "hostname": "headnode1",\
      "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",\
      "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",\
      "actions": {\
        "migrate": {\
          "available": false,\
          "reason_code": "vm-has-not-launched",\
          "reason_description": "string"\
        },\
        "rebuild": {\
          "available": false,\
          "reason_code": "vm-has-not-launched",\
          "reason_description": "string"\
        },\
        "restart": {\
          "available": false,\
          "reason_code": "vm-has-not-launched",\
          "reason_description": "string"\
        },\
        "cold_reboot": {\
          "available": false,\
          "reason_code": "vm-has-not-launched",\
          "reason_description": "string"\
        },\
        "terminate": {\
          "available": false,\
          "reason_code": "vm-has-not-launched",\
          "reason_description": "string"\
        }\
      },\
      "tags": [\
        {\
          "key": "key1",\
          "value": "value1"\
        }\
      ],\
      "firewall_rulesets": [\
        {\
          "id": "c4d291f47f9d436fa39f58493ce3b50d"\
        }\
      ]\
    }\
  ]
}

Live

Send a request to see the response.Send request

Retrieve instance details

GET/api/v1/instances/{id}

Retrieves the details of a specific instance, including whether or not the instance is running.

Path Parameters

• idstringrequired

The unique identifier (ID) of the instance

Response:200

• dataInstancerequired{

Detailed information about the instance.

• idstringrequired

The unique identifier of the instance.

• namestringoptional

If set, the user-provided name of the instance.

• Minimum length: 0

  • Maximum length: 64

• ipstringoptional

The public IPv4 address of the instance.

• private_ipstringoptional

The private IPv4 address of the instance.

• statusenumrequired

The current status of the instance.

Possible values: - "booting" - "active" - "unhealthy" - "terminated" - "terminating" - "preempted"

• ssh_key_namesarray of stringrequired[
  
  
  
  
  
  
  
  The names of the SSH keys that are allowed to access the instance.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• file_system_namesarray of stringrequired[
  
  
  
  
  
  
  
  The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• file_system_mountsarray of FilesystemMountEntryoptional[
  
  
  
  
  
  
  
  The filesystems, along with the mount paths, mounted to
  the instances. If no filesystems are mounted, this parameter
  will be missing from the response.
  
  
  
  
  
  
  \

  • FilesystemMountEntry{
    
    
    
    
    
    
    
    The mount point for a filesystem mounted to an instance.\

- mount_pointstringrequired







The absolute path indicating where on the instance the filesystem will be mounted.

- file_system_idstringrequired







The id of the filesystem to mount to the instance.


}

]

• regionRegionrequired{

The region in which the instance is deployed.

• namestringrequired

The region code.

• descriptionstringrequired

The region description.

}

• instance_typeInstanceTyperequired{

Detailed information about the instance's instance type.

• namestringrequired

The name of the instance type.

• descriptionstringrequired

A description of the instance type.

• gpu_descriptionstringrequired

The type of GPU used by this instance type.

• price_cents_per_hourintegerrequired

The price of the instance type in US cents per hour.

• specsInstanceTypeSpecsrequired{

Detailed technical specifications for the instance type.

• vcpusintegerrequired

The number of virtual CPUs.

• memory_gibintegerrequired

The amount of RAM in gibibytes (GiB).

• storage_gibintegerrequired

The amount of storage in gibibytes (GiB).

• gpusintegerrequired

The number of GPUs.

}

• architectureenumrequired

The CPU architecture of the instance type.

Possible values: - "x86_64" - "arm64"

}

• hostnamestringoptional

The hostname assigned to this instance, which resolves to the instance's IP.

• jupyter_tokenstringoptional

The secret token used to log into the JupyterLab server hosted on the instance.

• jupyter_urlstringoptional

The URL that opens the JupyterLab environment on the instance.

• actionsInstanceActionAvailabilityrequired{

A set of status objects representing the current availability of common instance operations.

• migrateInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• rebuildInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• restartInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• cold_rebootInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• terminateInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

}

• tagsarray of TagEntryoptional[
  
  
  
  
  
  
  
  Key/value pairs representing the instance's tags.
  
  
  
  
  
  
  \
  • TagEntry{
    
    
    
    
    
    
    \
    • keystringrequired\

The key of the tag.

- valuestringrequired







The value of the tag.


}

]

• firewall_rulesetsarray of FirewallRulesetEntryoptional[
  
  
  
  
  
  
  
  The firewall rulesets associated with this instance.
  
  
  
  
  
  
  \
  • FirewallRulesetEntry{
    
    
    
    
    
    
    
    Reference to a firewall ruleset.\

- idstringrequired







The unique identifier of the firewall ruleset.


}

]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"
• "global/forbidden"

404: Not FoundCollapse

• "global/object-does-not-exist"

Parameters & Request sampleCollapse

id

Reset params

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "name": "My Instance",
    "ip": "198.51.100.2",
    "private_ip": "10.0.2.100",
    "status": "booting",
    "ssh_key_names": [\
      "My SSH key"\
    ],
    "file_system_names": [\
      "my-filesystem"\
    ],
    "file_system_mounts": [\
      {\
        "mount_point": "/data/custom-mount-point",\
        "file_system_id": "398578a2336b49079e74043f0bd2cfe8"\
      }\
    ],
    "region": {
      "name": "string",
      "description": "string"
    },
    "instance_type": {
      "name": "gpu_8x_h100_sxm5gdr",
      "description": "8x H100 (80 GB SXM5)",
      "gpu_description": "H100 (80 GB SXM5)",
      "price_cents_per_hour": 3592,
      "specs": {
        "vcpus": 208,
        "memory_gib": 1800,
        "storage_gib": 24780,
        "gpus": 8
      },
      "architecture": "x86_64"
    },
    "hostname": "headnode1",
    "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",
    "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",
    "actions": {
      "migrate": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "rebuild": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "restart": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "cold_reboot": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "terminate": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      }
    },
    "tags": [\
      {\
        "key": "key1",\
        "value": "value1"\
      }\
    ],
    "firewall_rulesets": [\
      {\
        "id": "c4d291f47f9d436fa39f58493ce3b50d"\
      }\
    ]
  }
}

Live

Send a request to see the response.Send request

Update instance details

POST/api/v1/instances/{id}

Updates the details of the specified instance.

Path Parameters

• idstringrequired

The unique identifier (ID) of the instance

Body Parameters

• namestringoptional

The new, user-provided name for the instance.

• Minimum length: 0
  • Maximum length: 64

Response:200

• dataInstancerequired{

Detailed information about the instance.

• idstringrequired

The unique identifier of the instance.

• namestringoptional

If set, the user-provided name of the instance.

• Minimum length: 0

  • Maximum length: 64

• ipstringoptional

The public IPv4 address of the instance.

• private_ipstringoptional

The private IPv4 address of the instance.

• statusenumrequired

The current status of the instance.

Possible values: - "booting" - "active" - "unhealthy" - "terminated" - "terminating" - "preempted"

• ssh_key_namesarray of stringrequired[
  
  
  
  
  
  
  
  The names of the SSH keys that are allowed to access the instance.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• regionRegionrequired{

The region in which the instance is deployed.

• namestringrequired

The region code.

• descriptionstringrequired

The region description.

}

• instance_typeInstanceTyperequired{

Detailed information about the instance's instance type.

• namestringrequired

The name of the instance type.

• descriptionstringrequired

A description of the instance type.

• gpu_descriptionstringrequired

The type of GPU used by this instance type.

• price_cents_per_hourintegerrequired

The price of the instance type in US cents per hour.

• specsInstanceTypeSpecsrequired{

Detailed technical specifications for the instance type.

• vcpusintegerrequired

The number of virtual CPUs.

• memory_gibintegerrequired

The amount of RAM in gibibytes (GiB).

• storage_gibintegerrequired

The amount of storage in gibibytes (GiB).

• gpusintegerrequired

The number of GPUs.

}

• architectureenumrequired

The CPU architecture of the instance type.

Possible values: - "x86_64" - "arm64"

}

• hostnamestringoptional

The hostname assigned to this instance, which resolves to the instance's IP.

• jupyter_tokenstringoptional

The secret token used to log into the JupyterLab server hosted on the instance.

• jupyter_urlstringoptional

The URL that opens the JupyterLab environment on the instance.

• actionsInstanceActionAvailabilityrequired{

A set of status objects representing the current availability of common instance operations.

• migrateInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• rebuildInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• restartInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• cold_rebootInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

• terminateInstanceActionAvailabilityDetailsrequired{

Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

• availablebooleanrequired

If set, indicates that the relevant operation can be performed on the instance in its current state.

• reason_code(enum | string)optional

A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

Any ofCollapse

• enum

Possible values: - "vm-has-not-launched" - "vm-is-too-old" - "vm-is-terminating" - "vm-action-in-progress" - "vm-action-unavailable-bare-metal"

• string

• reason_descriptionstringoptional

A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

}

}

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/object-does-not-exist"

Parameters & Request sampleCollapse

id

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instances/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Instance"
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

Live

Send a request to see the response.Send request

Regions

List regions

GET/api/v1/regions

Retrieves a list of available regions.

Parameters

There are no parameters for this endpoint.

Response:200

• dataarray of Regionrequired[
  
  
  
  
  
  
  \
  • Region{
    
    
    
    
    
    
    \
    • namestringrequired
      
      
      
      
      
      
      
      The region code.\

- descriptionstringrequired







The region description.


}

]

Common Error Response Codes

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/regions' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "name": "string",\
      "description": "string"\
    }\
  ]
}

Live

Send a request to see the response.Send request

SSH keys

List your SSH keys

GET/api/v1/ssh-keys

Retrieves a list of your SSH keys.

Parameters

There are no parameters for this endpoint.

Response:200

• dataarray of SSHKeyrequired[
  
  
  
  
  
  
  \
  • SSHKey{
    
    
    
    
    
    
    
    Information about a stored SSH key that can be used to access instances over SSH.
    
    
    
    
    
    
    \
    • idstringrequired
      
      
      
      
      
      
      
      The unique identifier (ID) of the SSH key.\

- namestringrequired







The name of the SSH key.





- Minimum length: 1
- Maximum length: 64

- public_keystringrequired







The public key for the SSH key.





- Minimum length: 1
- Maximum length: 4096

}

]

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/ssh-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": [\
    {\
      "id": "ddf9a910ceb744a0bb95242cbba6cb50",\
      "name": "my-public-key",\
      "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICN+lJwsONkwrdsSnQsu1ydUkIuIg5oOC+Eslvmtt60T noname"\
    }\
  ]
}

Live

Send a request to see the response.Send request

Add an SSH key

POST/api/v1/ssh-keys

Add an SSH key to your Lambda Cloud account. You can upload an existing public key, or you can generate a new key pair.

• To use an existing key pair, set the public_key property in the request body to your public key.

• To generate a new key pair, omit the public_key property from the request body.

warning

Important

Lambda doesn't store your private key after it's been generated. If you generate a new key pair, make sure to save the resulting private key locally.

For example, to generate a new key pair and associate it with a Lambda On-Demand Cloud instance:

1. Generate the key pair. The command provided below automatically extracts and saves the returned private key to a new file called key.pem. Replace <NEW-KEY-NAME> with the name you want to assign to the SSH key:

curl --request POST --url 'https://cloud.lambda.ai/api/v1/ssh-keys' \
   --fail \
   --header "Authorization: Bearer ${LAMBDA_API_KEY}" \
   --data '{"name": "<NEW-KEY-NAME>"}' \
| jq -r '.data.private_key' > key.pem

2. Next, set the private key's permissions to read-only:

chmod 400 key.pem

3. Launch a new instance. Replace <NEW-KEY-NAME> with the name you assigned to your SSH key.

curl --request POST 'https://cloud.lambda.ai/api/v1/instance-operations/launch' \
   --fail \
   --header "Authorization: Bearer ${LAMBDA_API_KEY}" \
   --data '{"region_name":"us-west-1","instance_type_name":"gpu_1x_a10","ssh_key_names":["<NEW-KEY-NAME>"],"file_system_names":[],"quantity":1,"name":"My Instance"}'

4. From your local terminal, establish an SSH connection to the instance. Replace <INSTANCE-IP> with the public IP of the instance:

ssh -i key.pem <INSTANCE-IP>

Body Parameters

• namestringrequired

The name of the SSH key.

• Minimum length: 1

  • Maximum length: 64

• public_keystringoptional

The public key to store. Omit this to generate a new key pair.

• Minimum length: 1
  • Maximum length: 4096

Response:200

• data(GeneratedSSHKey | SSHKey)required

Any ofCollapse

• GeneratedSSHKey{

Information about a server-generated SSH key.

• idstringrequired

The unique identifier (ID) of the SSH key.

• namestringrequired

The name of the SSH key.

• Minimum length: 1 - Maximum length: 64

• public_keystringrequired

The public key for the SSH key.

• Minimum length: 1 - Maximum length: 4096

• private_keystringrequired

The private key generated in the SSH key pair. Store this value locally; Lambda does not retain the private key server-side.

}

• SSHKey{

Information about a stored SSH key that can be used to access instances over SSH.

• idstringrequired

The unique identifier (ID) of the SSH key.

• namestringrequired

The name of the SSH key.

• Minimum length: 1 - Maximum length: 64

• public_keystringrequired

The public key for the SSH key.

• Minimum length: 1 - Maximum length: 4096

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/ssh-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "my-public-key",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICN+lJwsONkwrdsSnQsu1ydUkIuIg5oOC+Eslvmtt60T noname"
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddf9a910ceb744a0bb95242cbba6cb50",
    "name": "my-public-key",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICN+lJwsONkwrdsSnQsu1ydUkIuIg5oOC+Eslvmtt60T noname",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\\n"
  }
}

Live

Send a request to see the response.Send request

Delete an SSH key

DELETE/api/v1/ssh-keys/{id}

Deletes the specified SSH key.

Path Parameters

• idstringrequired

The unique identifier (ID) of the SSH key to delete

Response:200

• dataEmptyResponserequired{

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

id

Reset params

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/ssh-keys/ddf9a910ceb744a0bb95242cbba6cb50' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {}
}

Live

Send a request to see the response.Send request

Support Tickets

The Lambda Support Ticketing API is currently in beta. Contact support to enable access.

List support tickets

GET/api/v1/tickets

Retrieves a list of support tickets for your account.

Query Parameters

• statusarray of enumoptional[
  
  
  
  
  
  
  
  The current status of a support ticket.
  
  
  
  
  
  
  \

  • enum
    
    
    
    
    
    
    
    The current status of a support ticket.
    
    
    
    
    
    
    Possible values: - "open"\
    • "on_hold"\
    • "pending"\
    • "solved"\
    • "confirm_solved"
      
      ]

• typearray of enumoptional[
  
  
  
  
  
  
  
  The type of support ticket.
  
  
  
  
  
  
  \

  • enum
    
    
    
    
    
    
    
    The type of support ticket.
    
    
    
    
    
    
    Possible values: - "service_request"\
    • "incident"\
    • "automated_event"
      
      ]

• severityarray of enumoptional[
  
  
  
  
  
  
  
  The severity level for incident tickets.
  
  
  
  
  
  
  \

  • enum
    
    
    
    
    
    
    
    The severity level for incident tickets.
    
    
    
    
    
    
    Possible values: - "sev_1"\
    • "sev_2"\
    • "sev_3"
      
      ]

• device_serialarray of stringoptional[
  
  
  
  
  
  
  
  The serial number of the affected device. Matching is case-insensitive.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• order_byenumoptional

Specifies the field used to sort the list of tickets.

Possible values: - "created_at"

• "updated_at"

• directionenumoptional

Specifies the order in which to sort the list of tickets.

Possible values: - "asc"

• "desc"

• page_tokenstringoptional

A page token. Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

Response:200

• dataTicketListResponserequired{

• ticketsarray of Ticketrequired[
  
  
  
  
  
  
  
  The current page of tickets.
  
  
  
  
  
  
  \

  • Ticket{
    
    
    
    
    
    
    \
    • idstringrequired\

The unique identifier for the ticket.

- subjectstringrequired







A short summary of the issue.

- descriptionstringrequired







The initial text provided when creating the issue or request.

- typeenumoptional







The type of support ticket.






Possible values: - "service_request"
- "incident"
- "automated_event"

- severityenumoptional







The severity level of the issue represented by the ticket. Omitted if the ticket isn't an incident.






Possible values: - "sev_1"
- "sev_2"
- "sev_3"

- statusenumrequired







The current status of the ticket.






Possible values: - "open"
- "on_hold"
- "pending"
- "solved"
- "confirm_solved"

- external_ticket_providerstringoptional







The external ticketing provider name (e.g., "zendesk").

- external_ticket_idstringoptional







The external provider ticket ID (e.g., Zendesk ticket ID).

- hostnamestringoptional







The hostname of the affected device.

- device_serialstringoptional







The serial number of the affected device.

- created_atstringrequired







The date and time at which the ticket was created. Formatted as an ISO 8601 timestamp.






Format: date-time

- updated_atstringoptional







The date and time at which the ticket was last updated. Formatted as an ISO 8601 timestamp.






Format: date-time

- resolved_atstringoptional







The date and time at which the ticket was resolved. Formatted as an ISO 8601 timestamp.






Format: date-time

- affected_devicesarray of stringoptional[







The list of devices affected by the issue.







- string


]

- commentsarray of TicketCommentrequired[







The ticket's full comment history.







- TicketComment{







- bodystringrequired







Comment text.

- authorstringrequired







The identifier of the comment author.

- created_atstringrequired







The date and time at which the comment was created. Formatted as an ISO 8601 timestamp.






Format: date-time


}

]

}

]

• page_token(string | null)required

A page token. Provide this token in your next request to retrieve the next page of results. Null if there are no additional pages.

Any ofCollapse

• string

• null

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

status

Press Enter to add multiple values.

type

Press Enter to add multiple values.

severity

Press Enter to add multiple values.

device_serial

Press Enter to add multiple values.

order_by

direction

page_token

Reset params

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "tickets": [\
      {\
        "id": "0920582c7ff041399e34823a0be62549",\
        "subject": "Node 12345 is experiencing an issue",\
        "description": "Performance drops by 30-40% during peak hours..",\
        "type": "incident",\
        "severity": "sev_1",\
        "status": "open",\
        "external_ticket_provider": "zendesk",\
        "external_ticket_id": "12345",\
        "hostname": "abc-gpu-001",\
        "device_serial": "SN123456789",\
        "created_at": "2024-10-20T10:15:00Z",\
        "updated_at": "2024-10-23T14:30:00Z",\
        "resolved_at": "2024-10-25T09:00:00Z",\
        "affected_devices": [\
          "abc-gpu-001",\
          "abc-gpu-002"\
        ],\
        "comments": [\
          {\
            "body": "Instance is experiencing high latency on GPU operations",\
            "author": "support-agent-123",\
            "created_at": "2024-10-23T14:30:00Z"\
          }\
        ]\
      }\
    ],
    "page_token": "string"
  }
}

Live

Send a request to see the response.Send request

Create a support ticket

POST/api/v1/tickets

Creates a new support ticket.

Body Parameters

• subjectstringrequired

A short summary of the issue.

• descriptionstringrequired

An initial description of the issue or request. When you make an API request to list the comments on this ticket, this will appear as the first public comment in the list.

• typeenumrequired

The type of support ticket.

Possible values: - "incident"

• "service_request"

• severityenumoptional

The severity level of the issue. Required for incident tickets, must not be provided for service requests.

Possible values: - "sev_1"

• "sev_2"

• "sev_3"

• ipstringoptional

The IP address of the affected node.

• instance_idstringoptional

The ID of the affected on-demand instance.

• cluster_idstringoptional

The ID of the affected 1CC or Supercluster.

• hostnamestringoptional

The hostname of the affected device.

• device_serialstringoptional

The serial number of the affected device.

• requester_emailstringoptional

The email address to associate with the ticket's requester.

• affected_devicesarray of stringoptional[
  
  
  
  
  
  
  
  The list of devices affected by the issue.
  
  
  
  
  
  
  \
  • string
    
    
    ]

Response:200

• dataTicketCreateResponserequired{

• idstringrequired

The unique identifier for the ticket.

• external_ticket_providerstringoptional

The external ticketing provider name (e.g., "zendesk").

• external_ticket_idstringoptional

The external provider ticket ID (e.g., Zendesk ticket ID).

• statusenumrequired

The current status of the ticket.

Possible values: - "open" - "on_hold" - "pending" - "solved" - "confirm_solved"

• typeenumrequired

The type of issue or request.

Possible values: - "service_request" - "incident" - "automated_event"

• severityenumoptional

The severity level of the issue represented by the ticket. Omitted if the ticket isn't an incident.

Possible values: - "sev_1" - "sev_2" - "sev_3"

• affected_devicesarray of stringoptional[
  
  
  
  
  
  
  
  The list of devices affected by the issue.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• hostnamestringoptional

The hostname of the affected device.

• device_serialstringoptional

The serial number of the affected device.

• created_atstringrequired

The date and time at which the ticket was created. Formatted as an ISO 8601 timestamp.

Format: date-time

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"
• "support-tickets/creation-failed"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"
• "global/forbidden"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

Request body

Reset params

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/tickets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "subject": "GPU cluster experiencing performance degradation",
  "description": "Performance drops by 30-40% during peak hours.",
  "type": "incident",
  "severity": "sev_1",
  "ip": "192.222.53.194",
  "instance_id": "2fbb7a309a7c475abe7ee58bd125ac36",
  "cluster_id": "a0bacf07268245a2b596b5863185a4ff",
  "hostname": "abc-gpu-001",
  "device_serial": "SN123456789",
  "requester_email": "alerts@example.com",
  "affected_devices": [\
    "abc-gpu-001",\
    "abc-gpu-002"\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "external_ticket_provider": "zendesk",
    "external_ticket_id": "12345",
    "status": "open",
    "type": "incident",
    "severity": "sev_1",
    "affected_devices": [\
      "abc-gpu-001",\
      "abc-gpu-002"\
    ],
    "hostname": "abc-gpu-001",
    "device_serial": "SN123456789",
    "created_at": "2024-10-20T10:15:00Z"
  }
}

Live

Send a request to see the response.Send request

Get a support ticket

GET/api/v1/tickets/{ticket_id}

Retrieves a specific support ticket by ID.

Path Parameters

• ticket_idstringrequired

The ticket ID.

Response:200

• dataTicketrequired{

• idstringrequired

The unique identifier for the ticket.

• subjectstringrequired

A short summary of the issue.

• descriptionstringrequired

The initial text provided when creating the issue or request.

• typeenumoptional

The type of support ticket.

Possible values: - "service_request" - "incident" - "automated_event"

• severityenumoptional

The severity level of the issue represented by the ticket. Omitted if the ticket isn't an incident.

Possible values: - "sev_1" - "sev_2" - "sev_3"

• statusenumrequired

The current status of the ticket.

Possible values: - "open" - "on_hold" - "pending" - "solved" - "confirm_solved"

• external_ticket_providerstringoptional

The external ticketing provider name (e.g., "zendesk").

• external_ticket_idstringoptional

The external provider ticket ID (e.g., Zendesk ticket ID).

• hostnamestringoptional

The hostname of the affected device.

• device_serialstringoptional

The serial number of the affected device.

• created_atstringrequired

The date and time at which the ticket was created. Formatted as an ISO 8601 timestamp.

Format: date-time

• updated_atstringoptional

The date and time at which the ticket was last updated. Formatted as an ISO 8601 timestamp.

Format: date-time

• resolved_atstringoptional

The date and time at which the ticket was resolved. Formatted as an ISO 8601 timestamp.

Format: date-time

• affected_devicesarray of stringoptional[
  
  
  
  
  
  
  
  The list of devices affected by the issue.
  
  
  
  
  
  
  \

  • string
    
    
    ]

• commentsarray of TicketCommentrequired[
  
  
  
  
  
  
  
  The ticket's full comment history.
  
  
  
  
  
  
  \

  • TicketComment{
    
    
    
    
    
    
    \
    • bodystringrequired\

Comment text.

- authorstringrequired







The identifier of the comment author.

- created_atstringrequired







The date and time at which the comment was created. Formatted as an ISO 8601 timestamp.






Format: date-time


}

]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

ticket_id

Reset params

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "subject": "Node 12345 is experiencing an issue",
    "description": "Performance drops by 30-40% during peak hours..",
    "type": "incident",
    "severity": "sev_1",
    "status": "open",
    "external_ticket_provider": "zendesk",
    "external_ticket_id": "12345",
    "hostname": "abc-gpu-001",
    "device_serial": "SN123456789",
    "created_at": "2024-10-20T10:15:00Z",
    "updated_at": "2024-10-23T14:30:00Z",
    "resolved_at": "2024-10-25T09:00:00Z",
    "affected_devices": [\
      "abc-gpu-001",\
      "abc-gpu-002"\
    ],
    "comments": [\
      {\
        "body": "Instance is experiencing high latency on GPU operations",\
        "author": "support-agent-123",\
        "created_at": "2024-10-23T14:30:00Z"\
      }\
    ]
  }
}

Live

Send a request to see the response.Send request

Update a support ticket

PATCH/api/v1/tickets/{ticket_id}

Updates a support ticket status or severity, or adds a comment to the ticket. Returns a 202. Ticket updates happen asynchronously so to see the result of an update, re-query the tickets API.

Path Parameters

• ticket_idstringrequired

The ticket ID.

Body Parameters

• statusstringoptional

The new status to set the ticket to.

• Const:

• severityenumoptional

The new severity level to set the ticket to.

Possible values: - "sev_1"

• "sev_2"

• "sev_3"

• commentTicketCommentInputoptional{

Adds a new comment.

• bodystringrequired

The text of the new comment.

}

• affected_devicesarray of stringoptional[
  
  
  
  
  
  
  
  The list of devices affected by the issue.
  
  
  
  
  
  
  \
  • string
    
    
    ]

Response:202

• dataEmptyResponserequired{

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

ticket_id

Request body

Reset params

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "status": "solved",
  "severity": "sev_2",
  "comment": {
    "body": "Turns out this was a non-issue on our end. Closing the ticket."
  },
  "affected_devices": [\
    "abc-gpu-001",\
    "abc-gpu-002"\
  ]
}'

Send request

ResponseCollapse

Sample

ResponseStatus: 202 Accepted

{
  "data": {}
}

Live

Send a request to see the response.Send request

List ticket attachments

GET/api/v1/tickets/{ticket_id}/attachments

Retrieves all attachments for a ticket.

Path Parameters

• ticket_idstringrequired

The ticket ID.

Query Parameters

• statusenumoptional

The current status of an attachment upload.

Possible values: - "pending"

• "uploaded"
• "failed"
• "deleted"

Response:200

• dataAttachmentListResponserequired{

Response containing list of attachments.

• attachmentsarray of Attachmentrequired[
  
  
  
  
  
  
  
  Retrieves all attachments associated with the specified ticket. If status is omitted, only uploaded attachments will be returned.
  
  
  
  
  
  
  \
  • Attachment{
    
    
    
    
    
    
    
    Attachment metadata.\

- idstringrequired







The unique identifier for the attachment.

- filenamestringrequired







The original filename.

- content_typestringrequired







The MIME type of the attached file.

- size_bytesintegerrequired







The attached file's size in bytes.

- upload_statusenumrequired







The current upload status of the attachment.






Possible values: - "pending"
- "uploaded"
- "failed"
- "deleted"

- uploaded_atstringoptional







The date and time at which the attachment finished uploading. Formatted as an ISO 8601 timestamp. Omitted if the attachment hasn't been uploaded yet.






Format: date-time

- created_atstringrequired







The date and time at which the attachment was created. Formatted as an ISO 8601 timestamp.






Format: date-time


}

]

}

Common Error Response Codes

400: Bad RequestCollapse

• "global/invalid-parameters"

401: UnauthorizedCollapse

• "global/invalid-api-key"

403: ForbiddenCollapse

• "global/account-inactive"
• "global/forbidden"

404: Not FoundCollapse

• "global/not-found"

Parameters & Request sampleCollapse

ticket_id

status

Reset params

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'

Send request

ResponseCollapse

Sample

ResponseStatus: 200 OK

{
  "data": {
    "attachments": [\
      {\
        "id": "0920582c7ff041399e34823a0be62549",\
        "filename": "debug-logs.tar.gz",\
        "content_type": "application/gzip",\
        "size_bytes": 1024000,\
        "upload_status": "uploaded",\
        "uploaded_at": "2024-10-20T10:15:00Z",\
        "created_at": "2024-10-20T10:10:00Z"\
      }\
    ]
  }
}

Live

Send a request to see the response.Send request

Initiate attachment upload

POST/api/v1/tickets/{ticket_id}/attachments

Start the upload process for a ticket attachment. Returns a presigned URL for direct upload to storage.

Path Parameters

• ticket_idstringrequired

The ticket ID.

Body Parameters

• filenamestringrequired

The original filename.

• Maximum length: 255

• content_typestringrequired