Skip to main content
GET
/
volumes
/
by-external-id
/
{externalId}
Get volume by external ID
curl --request GET \
  --url https://api.blaxel.ai/v0/volumes/by-external-id/{externalId} \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.blaxel.ai/v0/volumes/by-external-id/{externalId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.blaxel.ai/v0/volumes/by-external-id/{externalId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.blaxel.ai/v0/volumes/by-external-id/{externalId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.blaxel.ai/v0/volumes/by-external-id/{externalId}"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.blaxel.ai/v0/volumes/by-external-id/{externalId}")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.blaxel.ai/v0/volumes/by-external-id/{externalId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "metadata": {
    "name": "my-resource",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "createdBy": "<string>",
    "updatedBy": "<string>",
    "displayName": "My Resource",
    "externalId": "my-session-123",
    "labels": {},
    "plan": "<string>",
    "url": "<string>",
    "workspace": "<string>"
  },
  "spec": {
    "infrastructureId": "<string>",
    "region": "us-pdx-1",
    "size": 1024,
    "template": "mytemplate:latest"
  },
  "events": [
    {
      "canaryRevision": "<string>",
      "message": "Deployment successful",
      "revision": "rev-abc123",
      "status": "DEPLOYED",
      "time": "2025-01-15T10:30:00Z",
      "type": "deployment"
    }
  ],
  "state": {
    "attachedTo": "sandbox:my-sandbox"
  },
  "status": "<string>",
  "terminatedAt": "<string>"
}
{
"error": "Resource already exists",
"code": 409,
"message": "Invalid request body"
}
{
"error": "Resource already exists",
"code": 409,
"message": "Invalid request body"
}
{
"error": "Resource already exists",
"code": 409,
"message": "Invalid request body"
}
{
"error": "Resource already exists",
"code": 409,
"message": "Invalid request body"
}

Authorizations

Authorization
string
header
required

OAuth2 authentication with JWT tokens

Path Parameters

externalId
string
required

Caller-owned external identifier for the volume

Response

successful operation

Persistent storage volume that can be attached to sandboxes for durable file storage across sessions. Volumes survive sandbox deletion and can be reattached to new sandboxes.

metadata
object
required

Common metadata fields shared by all Blaxel resources including name, labels, timestamps, and ownership information

spec
object
required

Immutable volume configuration set at creation time (size and region cannot be changed after creation)

events
object[]
read-only

Events happening on a resource deployed on Blaxel

state
object
read-only

Current runtime state of the volume including attachment status

status
string
read-only

Volume status computed from events

terminatedAt
string
read-only

Timestamp when the volume was marked for termination

Last modified on July 9, 2026