Lambda Cloud API LogoLambda Cloud API Logo

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?,
        "request_id": 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.
  • request_id: Uniquely identifies the request that produced the error. Quote it when contacting support.
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:

Authorization: Bearer <token>

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:

Authorization: Bearer <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.

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

  • start string optional

    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
  • end string optional

    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_token string optional

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

  • resource_type string optional

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

Response:200

  • data array of AuditEvent required
    • 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_name string required

        The service in which the action was performed.

      • resource_name string required

        The type of resource that was affected.

      • action string required

        The action that was performed.

      • catalog_version string required

        The version of the event catalog schema.

      • event_id string required

        The unique identifier (ID) for this audit event.

      • event_time string required

        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 of
        • 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 of
        • 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 of
        • string
        • null
      • resource_lrns array of string required

        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 of
        • 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 of
        • string
        • null
      • workspace_lrn (string | null) required

        The Lambda Resource Name (LRN) of the workspace the affected resources belong to, if applicable.

        Any of
        • 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 of
        • 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 of
        • 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 of
        • 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 of
        • AuditResult

          The result of an audited action.

          • status enum required

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

            • Possible values:
              • "success"
              • "failure"
          • status_code (integer | null) optional
            Any of
            • integer
            • null
        • null
      • additional_details object required

        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 of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/audit-events' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
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",
      "workspace_lrn": "lrn:cloud:workspace:abcdef0123456789abcdef0123456789",
      "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.

Filesystems

List filesystems (deprecated path)

GET /api/v1/file-systems

Retrieves a list of your filesystems.

This path is deprecated in favor of GET /api/v1/filesystems, which is the spelling every other filesystem operation uses. The two return identical responses. This path is not scheduled for removal, so existing integrations keep working, but new ones should use /api/v1/filesystems.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Filesystem required
    • Filesystem

      Information about a shared filesystem.

      • id string required

        The unique identifier (ID) of the filesystem.

      • name string required

        The name of the filesystem.

      • mount_point string required

        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.

      • created string required

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

        • Format: date-time
      • created_by User required

        The user in your Team that created the filesystem.

        • id string required

          The unique identifier for the user.

        • email string required

          The email address of the user.

        • status enum required

          The status of the user's account.

          • Possible values:
            • "active"
            • "deactivated"
      • is_in_use boolean required

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

      • region Region required

        The region in which the filesystem is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • bytes_used integer optional

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

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

List filesystems

GET /api/v1/filesystems

Retrieves a list of your filesystems.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Filesystem required
    • Filesystem

      Information about a shared filesystem.

      • id string required

        The unique identifier (ID) of the filesystem.

      • name string required

        The name of the filesystem.

      • mount_point string required

        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.

      • created string required

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

        • Format: date-time
      • created_by User required

        The user in your Team that created the filesystem.

        • id string required

          The unique identifier for the user.

        • email string required

          The email address of the user.

        • status enum required

          The status of the user's account.

          • Possible values:
            • "active"
            • "deactivated"
      • is_in_use boolean required

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

      • region Region required

        The region in which the filesystem is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • bytes_used integer optional

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

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/filesystems' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
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.

Create filesystem

POST /api/v1/filesystems

Creates a new filesystem.

Body Parameters

  • name string required

    The name of the filesystem.

    • Minimum length: 1
    • Maximum length: 60
    • Regex pattern: ^[a-zA-Z]+[0-9a-zA-Z-]*$
  • region string required

    The region in which you want to create the filesystem.

Response:200

  • data Filesystem required

    Information about a shared filesystem.

    • id string required

      The unique identifier (ID) of the filesystem.

    • name string required

      The name of the filesystem.

    • mount_point string required

      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.

    • created string required

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

      • Format: date-time
    • created_by User required

      The user in your Team that created the filesystem.

      • id string required

        The unique identifier for the user.

      • email string required

        The email address of the user.

      • status enum required

        The status of the user's account.

        • Possible values:
          • "active"
          • "deactivated"
    • is_in_use boolean required

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

    • region Region required

      The region in which the filesystem is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • bytes_used integer optional

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

Common Error Response Codes

400: Bad Request
  • "global/duplicate"
  • "global/quota-exceeded"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/invalid-address"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
}'
Response
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.

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

  • id string required

    The unique identifier (ID) of the filesystem to delete

Response:200

  • data FilesystemDeleteResponse required
    • deleted_ids array of string required

      The unique identifiers of the filesystems that were deleted.

      • string

Common Error Response Codes

400: Bad Request
  • "filesystems/filesystem-in-use"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

ResponseStatus: 200 OK

{
  "data": {
    "deleted_ids": [
      "398578a2336b49079e74043f0bd2cfe8"
    ]
  }
}
Live
Send a request to see the response.

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

  • data array of FirewallRule required
    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        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_network string required

        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
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Common Error Response Codes

401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

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

  • data array of FirewallRule required

    The list of inbound firewall rules.

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        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_network string required

        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
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data array of FirewallRule required
    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        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_network string required

        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
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
    }
  ]
}'
Response
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.

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

  • data array of FirewallRuleset required
    • FirewallRuleset

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

      • id string required

        The unique identifier of the firewall ruleset.

      • name string required

        The name of the firewall ruleset.

      • region Region required

        The region in which the firewall ruleset is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • rules array of FirewallRule required

        The list of firewall rules in this ruleset.

        • FirewallRule
          • protocol enum required

            The protocol to which the rule applies.

            • Possible values:
              • "tcp"
              • "udp"
              • "icmp"
              • "all"
          • port_range array of integer optional

            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_network string required

            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
          • description string required

            A human-readable description of the rule.

            • Minimum length: 0
            • Maximum length: 128
      • created string required

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

        • Format: date-time
      • instance_ids array of string required

        The IDs of instances this firewall ruleset is associated with.

        • string

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

Create firewall ruleset

POST /api/v1/firewall-rulesets

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

Body Parameters

  • name string required

    The name of the firewall ruleset.

    • Maximum length: 64
  • region string required

    The region in which the firewall ruleset is deployed.

  • rules array of FirewallRule required

    The firewall rules to include in the ruleset.

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        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_network string required

        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
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data FirewallRuleset required

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

    • id string required

      The unique identifier of the firewall ruleset.

    • name string required

      The name of the firewall ruleset.

    • region Region required

      The region in which the firewall ruleset is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          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_network string required

          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
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128
    • created string required

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

      • Format: date-time
    • instance_ids array of string required

      The IDs of instances this firewall ruleset is associated with.

      • string

Common Error Response Codes

400: Bad Request
  • "global/quota-exceeded"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
    }
  ]
}'
Response
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.

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

  • data GlobalFirewallRuleset required

    Firewall rules that apply across all regions.

    • id string required

      The unique identifier of the firewall ruleset.

      • Const: "global"
    • name string required

      The name of the firewall ruleset.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          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_network string required

          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
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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>'
Response
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.

Update global firewall ruleset

PATCH /api/v1/firewall-rulesets/global

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

Body Parameters

  • rules array of FirewallRule optional

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

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        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_network string required

        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
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data GlobalFirewallRuleset required

    Firewall rules that apply across all regions.

    • id string required

      The unique identifier of the firewall ruleset.

      • Const: "global"
    • name string required

      The name of the firewall ruleset.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          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_network string required

          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
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
    }
  ]
}'
Response
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.

Retrieve firewall ruleset details

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

Retrieves the details of a specific firewall ruleset.

Path Parameters

  • id string required

    The unique identifier (ID) of the firewall ruleset

Response:200

  • data FirewallRuleset required

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

    • id string required

      The unique identifier of the firewall ruleset.

    • name string required

      The name of the firewall ruleset.

    • region Region required

      The region in which the firewall ruleset is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          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_network string required

          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
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128
    • created string required

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

      • Format: date-time
    • instance_ids array of string required

      The IDs of instances this firewall ruleset is associated with.

      • string

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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>'
Response
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.

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

  • id string required

    The unique identifier (ID) of the firewall ruleset

Body Parameters

  • name string optional

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

    • Maximum length: 64
  • rules array of FirewallRule optional

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

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        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_network string required

        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
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data FirewallRuleset required

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

    • id string required

      The unique identifier of the firewall ruleset.

    • name string required

      The name of the firewall ruleset.

    • region Region required

      The region in which the firewall ruleset is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          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_network string required

          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
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128
    • created string required

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

      • Format: date-time
    • instance_ids array of string required

      The IDs of instances this firewall ruleset is associated with.

      • string

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
    }
  ]
}'
Response
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.

Delete firewall ruleset

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

Deletes the firewall ruleset with the specified ID.

Path Parameters

  • id string required

    The unique identifier (ID) of the firewall ruleset

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "firewall-rulesets/firewall-ruleset-in-use"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

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

  • data array of Image required
    • Image

      An available machine image in Lambda Cloud.

      • id string required

        The unique identifier (ID) for an image.

      • created_time string required

        The date and time that the image was created.

        • Format: date-time
      • updated_time string required

        The date and time that the image was last updated.

        • Format: date-time
      • name string required

        The human-readable identifier for an image.

      • description string required

        Additional information about the image.

      • family string required

        The family the image belongs to.

      • version string required

        The image version.

      • architecture enum required

        The CPU architecture the image supports.

        • Possible values:
          • "x86_64"
          • "arm64"
      • region Region required

        The region in which this image is available.

        • name string required

          The region code.

        • description string required

          The region description.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

Instances

Launch instances

POST /api/v1/instance-operations/launch

Launches a Lambda On-Demand Cloud instance.

Body Parameters

  • region_name string required

    The region into which you want to launch the instance.

  • instance_type_name string required

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

  • ssh_key_names array of string required

    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_names array of string optional

    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_mounts array of RequestedFilesystemMountEntry optional

    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_point string required

        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_id string required

        The id of the filesystem to mount to the instance.

  • hostname string optional

    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}$
  • name string optional

    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 of
    • ImageSpecificationID

      Specifies the image to use by its unique identifier.

      • id string required
    • ImageSpecificationFamily

      Specifies the image to use by its family name.

      • family string required

        The family name of the image.

  • user_data string optional

    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
  • tags array of RequestedTagEntry optional

    Key/value pairs representing the instance's tags.

    • RequestedTagEntry
      • key string required

        The key of the tag. On instances, keys starting with lambda-ai- are reserved.

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

        The value of the tag.

        • Maximum length: 128
  • firewall_rulesets array of FirewallRulesetEntry optional

    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.

      • id string required

        The unique identifier of the firewall ruleset.

Response:200

  • data InstanceLaunchResponse required
    • instance_ids array of string required

      The unique identifiers (IDs) of the launched instances.

      • string

Common Error Response Codes

400: Bad Request
  • "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: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/invalid-address"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "instance_ids": [
      "0920582c7ff041399e34823a0be62549"
    ]
  }
}
Live
Send a request to see the response.

Restart instances

POST /api/v1/instance-operations/restart

Restarts one or more instances.

Body Parameters

  • instance_ids array of string required

    The unique identifiers (IDs) of the instances to restart.

    • string

Response:200

  • data InstanceRestartResponse required
    • restarted_instances array of Instance required

      The list of instances that were successfully restarted.

      • Instance

        Detailed information about the instance.

        • id string required

          The unique identifier of the instance.

        • name string optional

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

          • Minimum length: 0
          • Maximum length: 64
        • ip string optional

          The public IPv4 address of the instance.

        • private_ip string optional

          The private IPv4 address of the instance.

        • status enum required

          The current status of the instance.

          • Possible values:
            • "booting"
            • "active"
            • "unhealthy"
            • "terminated"
            • "terminating"
            • "preempted"
        • ssh_key_names array of string required

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

          • string
        • file_system_names array of string required

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

          • string
        • file_system_mounts array of FilesystemMountEntry optional

          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_point string required

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

            • file_system_id string required

              The id of the filesystem to mount to the instance.

        • region Region required

          The region in which the instance is deployed.

          • name string required

            The region code.

          • description string required

            The region description.

        • instance_type InstanceType required

          Detailed information about the instance's instance type.

          • name string required

            The name of the instance type.

          • description string required

            A description of the instance type.

          • gpu_description string required

            The type of GPU used by this instance type.

          • price_cents_per_hour integer required

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

          • specs InstanceTypeSpecs required

            Detailed technical specifications for the instance type.

            • vcpus integer required

              The number of virtual CPUs.

            • memory_gib integer required

              The amount of RAM in gibibytes (GiB).

            • storage_gib integer required

              The amount of storage in gibibytes (GiB).

            • gpus integer required

              The number of GPUs.

          • architecture enum required

            The CPU architecture of the instance type.

            • Possible values:
              • "x86_64"
              • "arm64"
        • image InstanceImage optional

          The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

          • id string required

            The unique identifier (ID) of the image.

          • family string required

            The family the image belongs to.

        • hostname string optional

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

        • jupyter_token string optional

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

        • jupyter_url string optional

          The URL that opens the JupyterLab environment on the instance.

        • actions InstanceActionAvailability required

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

          • migrate InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • rebuild InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • restart InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • cold_reboot InstanceActionAvailabilityDetails required

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

            Deprecated: use power_cycle instead, which reports the same availability.

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • power_cycle InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • terminate InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

        • tags array of TagEntry optional

          Key/value pairs representing the instance's tags.

          • TagEntry
            • key string required

              The key of the tag.

            • value string required

              The value of the tag.

        • firewall_rulesets array of FirewallRulesetEntry optional

          The firewall rulesets associated with this instance.

          • FirewallRulesetEntry

            Reference to a firewall ruleset.

            • id string required

              The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
409: Conflict
  • "global/conflict"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
  ]
}'
Response
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"
        },
        "workspace_id": "c8f3a2b17ff041399e34823a0be62549",
        "image": {
          "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
          "family": "ubuntu-lts"
        },
        "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
          },
          "power_cycle": {
            "available": true
          },
          "terminate": {
            "available": true
          }
        },
        "tags": [
          {
            "key": "key1",
            "value": "value1"
          },
          {
            "key": "key2",
            "value": "value2"
          }
        ]
      }
    ]
  }
}
Live
Send a request to see the response.

Terminate instances

POST /api/v1/instance-operations/terminate

Terminates one or more instances.

Body Parameters

  • instance_ids array of string required

    The unique identifiers (IDs) of the instances to terminate.

    • string

Response:200

  • data InstanceTerminateResponse required
    • terminated_instances array of Instance required

      The list of instances that were successfully terminated.

      • Instance

        Detailed information about the instance.

        • id string required

          The unique identifier of the instance.

        • name string optional

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

          • Minimum length: 0
          • Maximum length: 64
        • ip string optional

          The public IPv4 address of the instance.

        • private_ip string optional

          The private IPv4 address of the instance.

        • status enum required

          The current status of the instance.

          • Possible values:
            • "booting"
            • "active"
            • "unhealthy"
            • "terminated"
            • "terminating"
            • "preempted"
        • ssh_key_names array of string required

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

          • string
        • file_system_names array of string required

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

          • string
        • file_system_mounts array of FilesystemMountEntry optional

          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_point string required

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

            • file_system_id string required

              The id of the filesystem to mount to the instance.

        • region Region required

          The region in which the instance is deployed.

          • name string required

            The region code.

          • description string required

            The region description.

        • instance_type InstanceType required

          Detailed information about the instance's instance type.

          • name string required

            The name of the instance type.

          • description string required

            A description of the instance type.

          • gpu_description string required

            The type of GPU used by this instance type.

          • price_cents_per_hour integer required

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

          • specs InstanceTypeSpecs required

            Detailed technical specifications for the instance type.

            • vcpus integer required

              The number of virtual CPUs.

            • memory_gib integer required

              The amount of RAM in gibibytes (GiB).

            • storage_gib integer required

              The amount of storage in gibibytes (GiB).

            • gpus integer required

              The number of GPUs.

          • architecture enum required

            The CPU architecture of the instance type.

            • Possible values:
              • "x86_64"
              • "arm64"
        • image InstanceImage optional

          The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

          • id string required

            The unique identifier (ID) of the image.

          • family string required

            The family the image belongs to.

        • hostname string optional

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

        • jupyter_token string optional

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

        • jupyter_url string optional

          The URL that opens the JupyterLab environment on the instance.

        • actions InstanceActionAvailability required

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

          • migrate InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • rebuild InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • restart InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • cold_reboot InstanceActionAvailabilityDetails required

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

            Deprecated: use power_cycle instead, which reports the same availability.

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • power_cycle InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

          • terminate InstanceActionAvailabilityDetails required

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

            • available boolean required

              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 of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

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

        • tags array of TagEntry optional

          Key/value pairs representing the instance's tags.

          • TagEntry
            • key string required

              The key of the tag.

            • value string required

              The value of the tag.

        • firewall_rulesets array of FirewallRulesetEntry optional

          The firewall rulesets associated with this instance.

          • FirewallRulesetEntry

            Reference to a firewall ruleset.

            • id string required

              The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
  ]
}'
Response
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"
        },
        "workspace_id": "c8f3a2b17ff041399e34823a0be62549",
        "image": {
          "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
          "family": "ubuntu-lts"
        },
        "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
          },
          "power_cycle": {
            "available": true
          },
          "terminate": {
            "available": true
          }
        },
        "tags": [
          {
            "key": "key1",
            "value": "value1"
          },
          {
            "key": "key2",
            "value": "value2"
          }
        ]
      }
    ]
  }
}
Live
Send a request to see the response.

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

  • data InstanceTypes required
    • <string> InstanceTypesItem optional

      Detailed information and regional availability for the instance type.

      • instance_type InstanceType required

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

        • name string required

          The name of the instance type.

        • description string required

          A description of the instance type.

        • gpu_description string required

          The type of GPU used by this instance type.

        • price_cents_per_hour integer required

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

        • specs InstanceTypeSpecs required

          Detailed technical specifications for the instance type.

          • vcpus integer required

            The number of virtual CPUs.

          • memory_gib integer required

            The amount of RAM in gibibytes (GiB).

          • storage_gib integer required

            The amount of storage in gibibytes (GiB).

          • gpus integer required

            The number of GPUs.

        • architecture enum required

          The CPU architecture of the instance type.

          • Possible values:
            • "x86_64"
            • "arm64"
      • regions_with_capacity_available array of Region required

        A list of the regions in which this instance type is available.

        • Region
          • name string required

            The region code.

          • description string required

            The region description.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

List running instances

GET /api/v1/instances

Retrieves a list of your running instances.

Query Parameters

  • cluster_id string optional

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

Response:200

  • data array of Instance required
    • Instance

      Detailed information about the instance.

      • id string required

        The unique identifier of the instance.

      • name string optional

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

        • Minimum length: 0
        • Maximum length: 64
      • ip string optional

        The public IPv4 address of the instance.

      • private_ip string optional

        The private IPv4 address of the instance.

      • status enum required

        The current status of the instance.

        • Possible values:
          • "booting"
          • "active"
          • "unhealthy"
          • "terminated"
          • "terminating"
          • "preempted"
      • ssh_key_names array of string required

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

        • string
      • file_system_names array of string required

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

        • string
      • file_system_mounts array of FilesystemMountEntry optional

        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_point string required

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

          • file_system_id string required

            The id of the filesystem to mount to the instance.

      • region Region required

        The region in which the instance is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • instance_type InstanceType required

        Detailed information about the instance's instance type.

        • name string required

          The name of the instance type.

        • description string required

          A description of the instance type.

        • gpu_description string required

          The type of GPU used by this instance type.

        • price_cents_per_hour integer required

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

        • specs InstanceTypeSpecs required

          Detailed technical specifications for the instance type.

          • vcpus integer required

            The number of virtual CPUs.

          • memory_gib integer required

            The amount of RAM in gibibytes (GiB).

          • storage_gib integer required

            The amount of storage in gibibytes (GiB).

          • gpus integer required

            The number of GPUs.

        • architecture enum required

          The CPU architecture of the instance type.

          • Possible values:
            • "x86_64"
            • "arm64"
      • image InstanceImage optional

        The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

        • id string required

          The unique identifier (ID) of the image.

        • family string required

          The family the image belongs to.

      • hostname string optional

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

      • jupyter_token string optional

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

      • jupyter_url string optional

        The URL that opens the JupyterLab environment on the instance.

      • actions InstanceActionAvailability required

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

        • migrate InstanceActionAvailabilityDetails required

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

          • available boolean required

            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 of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

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

        • rebuild InstanceActionAvailabilityDetails required

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

          • available boolean required

            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 of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

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

        • restart InstanceActionAvailabilityDetails required

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

          • available boolean required

            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 of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

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

        • cold_reboot InstanceActionAvailabilityDetails required

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

          Deprecated: use power_cycle instead, which reports the same availability.

          • available boolean required

            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 of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

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

        • power_cycle InstanceActionAvailabilityDetails required

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

          • available boolean required

            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 of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

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

        • terminate InstanceActionAvailabilityDetails required

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

          • available boolean required

            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 of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

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

      • tags array of TagEntry optional

        Key/value pairs representing the instance's tags.

        • TagEntry
          • key string required

            The key of the tag.

          • value string required

            The value of the tag.

      • firewall_rulesets array of FirewallRulesetEntry optional

        The firewall rulesets associated with this instance.

        • FirewallRulesetEntry

          Reference to a firewall ruleset.

          • id string required

            The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
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"
      },
      "image": {
        "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
        "family": "ubuntu-lts"
      },
      "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"
        },
        "power_cycle": {
          "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.

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

  • id string required

    The unique identifier (ID) of the instance

Response:200

  • data Instance required

    Detailed information about the instance.

    • id string required

      The unique identifier of the instance.

    • name string optional

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

      • Minimum length: 0
      • Maximum length: 64
    • ip string optional

      The public IPv4 address of the instance.

    • private_ip string optional

      The private IPv4 address of the instance.

    • status enum required

      The current status of the instance.

      • Possible values:
        • "booting"
        • "active"
        • "unhealthy"
        • "terminated"
        • "terminating"
        • "preempted"
    • ssh_key_names array of string required

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

      • string
    • file_system_names array of string required

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

      • string
    • file_system_mounts array of FilesystemMountEntry optional

      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_point string required

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

        • file_system_id string required

          The id of the filesystem to mount to the instance.

    • region Region required

      The region in which the instance is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • instance_type InstanceType required

      Detailed information about the instance's instance type.

      • name string required

        The name of the instance type.

      • description string required

        A description of the instance type.

      • gpu_description string required

        The type of GPU used by this instance type.

      • price_cents_per_hour integer required

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

      • specs InstanceTypeSpecs required

        Detailed technical specifications for the instance type.

        • vcpus integer required

          The number of virtual CPUs.

        • memory_gib integer required

          The amount of RAM in gibibytes (GiB).

        • storage_gib integer required

          The amount of storage in gibibytes (GiB).

        • gpus integer required

          The number of GPUs.

      • architecture enum required

        The CPU architecture of the instance type.

        • Possible values:
          • "x86_64"
          • "arm64"
    • image InstanceImage optional

      The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

      • id string required

        The unique identifier (ID) of the image.

      • family string required

        The family the image belongs to.

    • hostname string optional

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

    • jupyter_token string optional

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

    • jupyter_url string optional

      The URL that opens the JupyterLab environment on the instance.

    • actions InstanceActionAvailability required

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

      • migrate InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • rebuild InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • restart InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • cold_reboot InstanceActionAvailabilityDetails required

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

        Deprecated: use power_cycle instead, which reports the same availability.

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • power_cycle InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • terminate InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

    • tags array of TagEntry optional

      Key/value pairs representing the instance's tags.

      • TagEntry
        • key string required

          The key of the tag.

        • value string required

          The value of the tag.

    • firewall_rulesets array of FirewallRulesetEntry optional

      The firewall rulesets associated with this instance.

      • FirewallRulesetEntry

        Reference to a firewall ruleset.

        • id string required

          The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
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"
    },
    "image": {
      "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
      "family": "ubuntu-lts"
    },
    "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"
      },
      "power_cycle": {
        "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.

Update instance details

POST /api/v1/instances/{id}

Updates the details of the specified instance.

Path Parameters

  • id string required

    The unique identifier (ID) of the instance

Body Parameters

  • name string optional

    The new, user-provided name for the instance.

    • Minimum length: 0
    • Maximum length: 64
  • tags array of RequestedTagEntry optional

    The new tags for the instance. If provided, this replaces the existing tags (an empty list clears them). If not provided, the tags will not be updated.

    • RequestedTagEntry
      • key string required

        The key of the tag. On instances, keys starting with lambda-ai- are reserved.

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

        The value of the tag.

        • Maximum length: 128

Response:200

  • data Instance required

    Detailed information about the instance.

    • id string required

      The unique identifier of the instance.

    • name string optional

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

      • Minimum length: 0
      • Maximum length: 64
    • ip string optional

      The public IPv4 address of the instance.

    • private_ip string optional

      The private IPv4 address of the instance.

    • status enum required

      The current status of the instance.

      • Possible values:
        • "booting"
        • "active"
        • "unhealthy"
        • "terminated"
        • "terminating"
        • "preempted"
    • ssh_key_names array of string required

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

      • string
    • file_system_names array of string required

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

      • string
    • file_system_mounts array of FilesystemMountEntry optional

      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_point string required

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

        • file_system_id string required

          The id of the filesystem to mount to the instance.

    • region Region required

      The region in which the instance is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • instance_type InstanceType required

      Detailed information about the instance's instance type.

      • name string required

        The name of the instance type.

      • description string required

        A description of the instance type.

      • gpu_description string required

        The type of GPU used by this instance type.

      • price_cents_per_hour integer required

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

      • specs InstanceTypeSpecs required

        Detailed technical specifications for the instance type.

        • vcpus integer required

          The number of virtual CPUs.

        • memory_gib integer required

          The amount of RAM in gibibytes (GiB).

        • storage_gib integer required

          The amount of storage in gibibytes (GiB).

        • gpus integer required

          The number of GPUs.

      • architecture enum required

        The CPU architecture of the instance type.

        • Possible values:
          • "x86_64"
          • "arm64"
    • image InstanceImage optional

      The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

      • id string required

        The unique identifier (ID) of the image.

      • family string required

        The family the image belongs to.

    • hostname string optional

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

    • jupyter_token string optional

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

    • jupyter_url string optional

      The URL that opens the JupyterLab environment on the instance.

    • actions InstanceActionAvailability required

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

      • migrate InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • rebuild InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • restart InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • cold_reboot InstanceActionAvailabilityDetails required

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

        Deprecated: use power_cycle instead, which reports the same availability.

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • power_cycle InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

      • terminate InstanceActionAvailabilityDetails required

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

        • available boolean required

          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 of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

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

    • tags array of TagEntry optional

      Key/value pairs representing the instance's tags.

      • TagEntry
        • key string required

          The key of the tag.

        • value string required

          The value of the tag.

    • firewall_rulesets array of FirewallRulesetEntry optional

      The firewall rulesets associated with this instance.

      • FirewallRulesetEntry

        Reference to a firewall ruleset.

        • id string required

          The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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",
  "tags": [
    {
      "key": "key1",
      "value": "value1"
    }
  ]
}'
Response
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"
    },
    "image": {
      "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
      "family": "ubuntu-lts"
    },
    "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"
      },
      "power_cycle": {
        "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.

Regions

List regions

GET /api/v1/regions

Retrieves a list of available regions.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Region required
    • Region
      • name string required

        The region code.

      • description string required

        The region description.

Common Error Response Codes

401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

ResponseStatus: 200 OK

{
  "data": [
    {
      "name": "string",
      "description": "string"
    }
  ]
}
Live
Send a request to see the response.

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

  • data array of SSHKey required
    • SSHKey

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

      • id string required

        The unique identifier (ID) of the SSH key.

      • name string required

        The name of the SSH key.

        • Minimum length: 1
        • Maximum length: 64
      • public_key string required

        The public key for the SSH key.

        • Minimum length: 1
        • Maximum length: 4096

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

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

  • name string required

    The name of the SSH key.

    • Minimum length: 1
    • Maximum length: 64
  • public_key string optional

    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 of
    • GeneratedSSHKey

      Information about a server-generated SSH key.

      • id string required

        The unique identifier (ID) of the SSH key.

      • name string required

        The name of the SSH key.

        • Minimum length: 1
        • Maximum length: 64
      • public_key string required

        The public key for the SSH key.

        • Minimum length: 1
        • Maximum length: 4096
      • private_key string required

        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.

      • id string required

        The unique identifier (ID) of the SSH key.

      • name string required

        The name of the SSH key.

        • Minimum length: 1
        • Maximum length: 64
      • public_key string required

        The public key for the SSH key.

        • Minimum length: 1
        • Maximum length: 4096

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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"
}'
Response
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.

Delete an SSH key

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

Deletes the specified SSH key.

Path Parameters

  • id string required

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

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

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

  • status array of enum optional

    The current status of a support ticket.

    • enum

      The current status of a support ticket.

      • Possible values:
        • "open"
        • "on_hold"
        • "pending"
        • "solved"
        • "confirm_solved"
  • type array of enum optional

    The type of support ticket.

    • enum

      The type of support ticket.

      • Possible values:
        • "service_request"
        • "incident"
        • "automated_event"
  • severity array of enum optional

    The severity level for incident tickets.

    • enum

      The severity level for incident tickets.

      • Possible values:
        • "sev_1"
        • "sev_2"
        • "sev_3"
  • priority array of enum optional

    The priority level of a support ticket.

    • enum

      The priority level of a support ticket.

      • Possible values:
        • "low"
        • "normal"
        • "high"
        • "urgent"
  • device_serial array of string optional

    The serial number of the affected device. Matching is case-insensitive.

    • string
  • order_by enum optional

    Specifies the field used to sort the list of tickets.

    • Possible values:
      • "created_at"
      • "updated_at"
  • direction enum optional

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

    • Possible values:
      • "asc"
      • "desc"
  • page_token string optional

    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

  • data TicketListResponse required
    • tickets array of Ticket required

      The current page of tickets.

      • Ticket
        • id string required

          The unique identifier for the ticket.

        • subject string required

          A short summary of the issue.

        • description string required

          The initial text provided when creating the issue or request.

        • type enum optional

          The type of support ticket.

          • Possible values:
            • "service_request"
            • "incident"
            • "automated_event"
        • severity enum optional

          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"
        • priority enum optional

          The priority level of the ticket.

          • Possible values:
            • "low"
            • "normal"
            • "high"
            • "urgent"
        • status enum required

          The current status of the ticket.

          • Possible values:
            • "open"
            • "on_hold"
            • "pending"
            • "solved"
            • "confirm_solved"
        • external_ticket_provider string optional

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

        • external_ticket_id string optional

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

        • hostname string optional

          The hostname of the affected device.

        • device_serial string optional

          The serial number of the affected device.

        • created_at string required

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

          • Format: date-time
        • updated_at string optional

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

          • Format: date-time
        • resolved_at string optional

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

          • Format: date-time
        • affected_devices array of string optional

          The list of devices affected by the issue.

          • string
        • comments array of TicketComment required

          The ticket's full comment history.

          • TicketComment
            • body string required

              Comment text.

            • author string required

              The identifier of the comment author.

            • created_at string required

              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 of
      • string
      • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample
Press Enter to add multiple values.
Press Enter to add multiple values.
Press Enter to add multiple values.
Press Enter to add multiple values.
Press Enter to add multiple values.

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
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",
        "priority": "high",
        "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.

Create a support ticket

POST /api/v1/tickets

Creates a new support ticket.

Body Parameters

  • subject string required

    A short summary of the issue.

  • description string required

    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.

  • type enum required

    The type of support ticket.

    • Possible values:
      • "incident"
      • "service_request"
  • severity enum optional

    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"
  • priority enum optional

    The priority level of the ticket.

    • Possible values:
      • "low"
      • "normal"
      • "high"
      • "urgent"
  • ip string optional

    The IP address of the affected node.

  • instance_id string optional

    The ID of the affected on-demand instance.

  • cluster_id string optional

    The ID of the affected 1CC or Supercluster.

  • hostname string optional

    The hostname of the affected device.

  • device_serial string optional

    The serial number of the affected device.

  • requester_email string optional

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

  • affected_devices array of string optional

    The list of devices affected by the issue.

    • string

Response:200

  • data TicketCreateResponse required
    • id string required

      The unique identifier for the ticket.

    • external_ticket_provider string optional

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

    • external_ticket_id string optional

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

    • status enum required

      The current status of the ticket.

      • Possible values:
        • "open"
        • "on_hold"
        • "pending"
        • "solved"
        • "confirm_solved"
    • type enum required

      The type of issue or request.

      • Possible values:
        • "service_request"
        • "incident"
        • "automated_event"
    • severity enum optional

      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"
    • priority enum optional

      The priority level of the ticket.

      • Possible values:
        • "low"
        • "normal"
        • "high"
        • "urgent"
    • affected_devices array of string optional

      The list of devices affected by the issue.

      • string
    • hostname string optional

      The hostname of the affected device.

    • device_serial string optional

      The serial number of the affected device.

    • created_at string required

      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 Request
  • "global/invalid-parameters"
  • "support-tickets/creation-failed"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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",
  "priority": "high",
  "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"
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "external_ticket_provider": "zendesk",
    "external_ticket_id": "12345",
    "status": "open",
    "type": "incident",
    "severity": "sev_1",
    "priority": "high",
    "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.

Get a support ticket

GET /api/v1/tickets/{ticket_id}

Retrieves a specific support ticket by ID.

Path Parameters

  • ticket_id string required

    The ticket ID.

Response:200

  • data Ticket required
    • id string required

      The unique identifier for the ticket.

    • subject string required

      A short summary of the issue.

    • description string required

      The initial text provided when creating the issue or request.

    • type enum optional

      The type of support ticket.

      • Possible values:
        • "service_request"
        • "incident"
        • "automated_event"
    • severity enum optional

      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"
    • priority enum optional

      The priority level of the ticket.

      • Possible values:
        • "low"
        • "normal"
        • "high"
        • "urgent"
    • status enum required

      The current status of the ticket.

      • Possible values:
        • "open"
        • "on_hold"
        • "pending"
        • "solved"
        • "confirm_solved"
    • external_ticket_provider string optional

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

    • external_ticket_id string optional

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

    • hostname string optional

      The hostname of the affected device.

    • device_serial string optional

      The serial number of the affected device.

    • created_at string required

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

      • Format: date-time
    • updated_at string optional

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

      • Format: date-time
    • resolved_at string optional

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

      • Format: date-time
    • affected_devices array of string optional

      The list of devices affected by the issue.

      • string
    • comments array of TicketComment required

      The ticket's full comment history.

      • TicketComment
        • body string required

          Comment text.

        • author string required

          The identifier of the comment author.

        • created_at string required

          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 Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
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",
    "priority": "high",
    "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.

Update a support ticket

PATCH /api/v1/tickets/{ticket_id}

Updates a support ticket status, severity, or priority, 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_id string required

    The ticket ID.

Body Parameters

  • status string optional

    The new status to set the ticket to.

    • Const: "solved"
  • severity enum optional

    The new severity level to set the ticket to.

    • Possible values:
      • "sev_1"
      • "sev_2"
      • "sev_3"
  • priority enum optional

    The new priority level to set the ticket to.

    • Possible values:
      • "low"
      • "normal"
      • "high"
      • "urgent"
  • comment TicketCommentInput optional

    Adds a new comment.

    • body string required

      The text of the new comment.

  • affected_devices array of string optional

    The list of devices affected by the issue.

    • string

Response:202

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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",
  "priority": "high",
  "comment": {
    "body": "Turns out this was a non-issue on our end. Closing the ticket."
  },
  "affected_devices": [
    "abc-gpu-001",
    "abc-gpu-002"
  ]
}'
Response
Sample

ResponseStatus: 202 Accepted

{
  "data": {}
}
Live
Send a request to see the response.

List ticket attachments

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

Retrieves all attachments for a ticket.

Path Parameters

  • ticket_id string required

    The ticket ID.

Query Parameters

  • status enum optional

    The current status of an attachment upload.

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

Response:200

  • data AttachmentListResponse required

    Response containing list of attachments.

    • attachments array of Attachment required

      Retrieves all attachments associated with the specified ticket. If status is omitted, only uploaded attachments will be returned.

      • Attachment

        Attachment metadata.

        • id string required

          The unique identifier for the attachment.

        • filename string required

          The original filename.

        • content_type string required

          The MIME type of the attached file.

        • size_bytes integer required

          The attached file's size in bytes.

        • upload_status enum required

          The current upload status of the attachment.

          • Possible values:
            • "pending"
            • "uploaded"
            • "failed"
            • "deleted"
        • uploaded_at string optional

          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_at string required

          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 Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

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>'
Response
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.

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_id string required

    The ticket ID.

Body Parameters

  • filename string required

    The original filename.

    • Maximum length: 255
  • content_type string required

    The MIME type of the attachment, such as application/gzip for a .gz file or text/plain for a plaintext file.

  • size_bytes integer required

    The file size in bytes. The file size must be one or more bytes.

    • Minimum : 1

Response:200

  • data AttachmentInitiateResponse required

    Response with upload instructions.

    • attachment_id string required

      The unique identifier for the attachment.

    • upload_url string required

      A presigned URL. Use this URL to directly upload the attachment to storage.

    • upload_method string required

      The HTTP method to use when uploading your attachment (PUT or POST).

    • upload_status enum required

      The current upload status of your attachment.

      • Possible values:
        • "pending"
        • "uploaded"
        • "failed"
        • "deleted"
    • expires_in integer required

      The window of time, in seconds, that the provided presigned URL is available to be uploaded to.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "filename": "debug-logs.tar.gz",
  "content_type": "application/gzip",
  "size_bytes": 1024000
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "attachment_id": "0920582c7ff041399e34823a0be62549",
    "upload_url": "https://s3.amazonaws.com/...presigned-url",
    "upload_method": "PUT",
    "upload_status": "pending",
    "expires_in": 3600
  }
}
Live
Send a request to see the response.

Delete attachment

DELETE /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

Delete an attachment.

Path Parameters

  • ticket_id string required

    The ticket ID.

  • attachment_id string required

    The attachment ID.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

Complete attachment upload

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

Mark attachment upload as complete after client finishes uploading to storage.

Path Parameters

  • ticket_id string required

    The ticket ID.

  • attachment_id string required

    The attachment ID.

Response:200

  • data Attachment required

    Attachment metadata.

    • id string required

      The unique identifier for the attachment.

    • filename string required

      The original filename.

    • content_type string required

      The MIME type of the attached file.

    • size_bytes integer required

      The attached file's size in bytes.

    • upload_status enum required

      The current upload status of the attachment.

      • Possible values:
        • "pending"
        • "uploaded"
        • "failed"
        • "deleted"
    • uploaded_at string optional

      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_at string required

      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 Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

ResponseStatus: 200 OK

{
  "data": {
    "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.

Get attachment download URL

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

Generate a temporary download URL for an attachment.

Path Parameters

  • ticket_id string required

    The ticket ID.

  • attachment_id string required

    The attachment ID.

Response:200

  • data AttachmentDownloadResponse required

    The response with the download URL.

    • download_url string required

      A presigned URL for downloading the file.

    • expires_in integer required

      The URL expiration time in seconds.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

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

ResponseStatus: 200 OK

{
  "data": {
    "download_url": "https://s3.amazonaws.com/...presigned-download-url",
    "expires_in": 3600
  }
}
Live
Send a request to see the response.