---
title: "Get drive by external ID"
method: GET
path: "/drives/by-external-id/{externalId}"
tags: ["drives"]
---

# Get drive by external ID

`GET /drives/by-external-id/{externalId}`

## Request

- Base URL: `https://api.blaxel.ai/v0`
- URL: `https://api.blaxel.ai/v0/drives/by-external-id/{externalId}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Client credentials
    - Token URL: `/oauth/token` scopes: `drives:get`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/blaxel/apis/blaxel-control-plane/docs/drives/by-external-id/:externalId/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a drive matching the given external ID. If no drive is found, returns 404.

## Response `200`

successful operation

- Drive: Drive providing persistent storage that can be attached to agents, functions, and sandboxes. Drives can be mounted at runtime via the sbx API.
  - `events` CoreEvent[]: Events happening on a resource deployed on Blaxel
    - `canaryRevision` string: Canary revisionID link to the event
    - `message` string: Event message
    - `revision` string: RevisionID link to the event
    - `status` string: Event status
    - `time` string: Event time
    - `type` string: Event type
  - `metadata` Metadata, required: Owner fields for Persistence
    - `createdAt` string: The date and time when the resource was created
    - `updatedAt` string: The date and time when the resource was updated
    - `createdBy` string: The user or service account who created the resource
    - `updatedBy` string: The user or service account who updated the resource
    - `displayName` string: Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
    - `externalId` string: Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
    - `labels` MetadataLabels: Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
    - `name` string, required: Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
    - `plan` string: Billing plan tier applied to this resource (inherited from workspace account)
    - `url` string: Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
    - `workspace` string: Name of the workspace this resource belongs to (read-only, set automatically)
  - `spec` DriveSpec, required: Immutable drive configuration set at creation time
    - `infrastructureId` string: The internal infrastructure resource identifier for this drive (bucket name)
    - `permissions` DrivePermission[]: Permissions controlling which workloads can access this drive. Empty means all workloads in the workspace can access the drive. Maximum 3 permissions.
      - `labels` object: Labels that the workload must have. All labels must match (AND logic). Empty labels match all workloads.
      - `mode` 'read' | 'read-write': Access mode granted by this permission
      - `path` string: Subfolder path to restrict access to. Defaults to / (full drive).
    - `region` string: Deployment region for the drive (e.g., us-pdx-1, eu-lon-1). Must match the region of resources it attaches to.
    - `size` integer: Optional size limit for the drive in GB. If not specified, drive has no size limit.
  - `state` DriveState: Current runtime state of the drive
    - `s3Url` string: S3-compatible endpoint URL for accessing drive contents
  - `status` string: Drive status computed from events

## Other responses

- `401`: Unauthorized
- `403`: Forbidden - Insufficient permissions to view drives
- `404`: Drive not found
- `500`: Internal server error

---

[API](https://skmtc.dev/blaxel/apis/blaxel-control-plane.md) - [All operations](https://skmtc.dev/blaxel/apis/blaxel-control-plane/llms.txt) - [OpenAPI document](https://skmtc.dev/blaxel/apis/blaxel-control-plane/revisions/dfa264bc72ee?raw)