Skip to content
For Self-Managed AI Platform users running v11.1, see the on-premise platform documentation
Self-managed installation and maintenance > Backup and restore > Restore procedure > Restore notebooks and codespaces

Restore notebooks and codespaces

Notebooks and codespaces can be restored from backup using either CLI commands or the Admin API. Restoration is available within the configured retention window (default: 30 days).

Prerequisites

Note

You must fulfill the prerequisites before proceeding.

  • Cluster access with appropriate credentials
  • Access to a shell in the notebooks-data-retention service pod.
  • Notebook or codespace IDs to restore.
  • The User ID of the person requesting the restoration.

Important

Codespace file storage can only be restored if Kubernetes Volume Snapshots were configured before backup. Classic notebooks and standalone notebooks do not require Volume Snapshots.

CLI commands (recommended)

Step 1: Access the data-retention service pod

kubectl exec -it -n <namespace> deployment/notebooks-data-retention -- /bin/bash

Step 2: Find available backups

Query notebooks and codespaces available for restoration using whichever filter applies:

# By organization ID
python services/data_retention/commands/ restorations available --org-id <ORG_ID>

# By tenant ID
python services/data_retention/commands/ restorations available --tenant-id <TENANT_ID>

# By user ID
python services/data_retention/commands/ restorations available --user-id <USER_ID>

# By Use Case ID
python services/data_retention/commands/ restorations available --use-case-id <USE_CASE_ID>

# By specific notebook IDs
python services/data_retention/commands/ restorations available --notebook-id <NOTEBOOK_ID> --notebook-id <NOTEBOOK_ID>

# Include notebooks whose Use Case was also deleted
python services/data_retention/commands/ restorations available --user-id <USER_ID> --allow-deleted-use-cases

The output lists available items with notebook ID, name, owner, type, deletion date, and associated Use Case.

Step 3: Restore

# Restore a single notebook or codespace
python services/data_retention/commands/ restorations create <REQUESTER_ID> <NOTEBOOK_ID>

# Restore multiple notebooks or codespaces
python services/data_retention/commands/ restorations create <REQUESTER_ID> <NOTEBOOK_ID_1> <NOTEBOOK_ID_2>

# Restore when the associated Use Case was deleted
python services/data_retention/commands/ restorations create <REQUESTER_ID> <NOTEBOOK_ID> --allow-deleted-use-cases
  • <REQUESTER_ID>: User ID of the admin or support person performing the restore.
  • <NOTEBOOK_ID>: ID of the notebook or codespace to restore. Can be repeated.
  • --allow-deleted-use-cases: Required when the associated Use Case no longer exists. A new Use Case named [DataRobot] Restoration Use Case is created automatically.

The command runs synchronously and outputs confirmation when complete.

Built-in help

python services/data_retention/commands/ restorations --help
python services/data_retention/commands/ restorations available --help
python services/data_retention/commands/ restorations create --help

Admin API

The Admin API provides the same restoration functionality as the CLI but asynchronously, scoped to the organization of the Admin user making the request.

Step 1: List available restorations

Find notebooks and codespaces available for restoration. Exactly one filter must be provided.

# By user ID
curl -s -X POST "https://<DATAROBOT_HOST>/api-gw/nbx/admin-api/restorations/available/" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"userId": "<USER_ID>"}'

# By Use Case ID
curl -s -X POST "https://<DATAROBOT_HOST>/api-gw/nbx/admin-api/restorations/available/" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"useCaseId": "<USE_CASE_ID>"}'

# By specific notebook IDs
curl -s -X POST "https://<DATAROBOT_HOST>/api-gw/nbx/admin-api/restorations/available/" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"notebookIds": ["<NOTEBOOK_ID_1>", "<NOTEBOOK_ID_2>"]}'

Response:

{
  "restorations": [
    {
      "notebookId": "66f1a2b3c4d5e6f7a8b9c0d1",
      "notebookName": "My Analysis",
      "userId": "66f1a2b3c4d5e6f7a8b9c0d2",
      "hardDeleteScheduledAt": "2025-04-01T12:00:00Z",
      "notebookType": "standalone",
      "useCaseDeletedState": "not_deleted"
    }
  ]
}

notebookType is one of classic, standalone, or codespace. useCaseDeletedState is one of not_deleted, soft_deleted, or deleted.

Step 2: Create restoration request

Submit a restoration request with the notebook IDs from Step 1:

curl -s -X POST "https://<DATAROBOT_HOST>/api-gw/nbx/admin-api/restorations/" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"notebookIds": ["<NOTEBOOK_ID_1>", "<NOTEBOOK_ID_2>"]}'

Response:

{
  "restorationRequestId": "66f1a2b3c4d5e6f7a8b9c0d3"
}

Step 3: Poll for completion

Poll until status reaches a final state:

curl -s "https://<DATAROBOT_HOST>/api-gw/nbx/admin-api/restorations/<RESTORATION_REQUEST_ID>/" \
  -H "Authorization: Bearer <API_TOKEN>"

Response:

{
  "id": "66f1a2b3c4d5e6f7a8b9c0d3",
  "status": "restored",
  "notebookIds": ["66f1a2b3c4d5e6f7a8b9c0d1"],
  "restoredNotebookIds": ["66f1a2b3c4d5e6f7a8b9c0d1"],
  "requesterId": "66f1a2b3c4d5e6f7a8b9c0d4",
  "createdAt": "2025-03-01T10:00:00Z",
  "updatedAt": "2025-03-01T10:01:30Z"
}

Final status values: restored, partially_restored, restoration_failed. Intermediate values: claimed, in_progress.

Notes

  • Scheduled notebooks: Schedules are restored in a disabled state. Re-enable them manually after restoration.
  • Deleted Use Cases: Use --allow-deleted-use-cases; a new umbrella Use Case is created on behalf of the owner. The owner must exist and be active.
  • Expired backups: Notebooks and codespaces cannot be restored after the retention window has passed.

Troubleshooting

Issue Cause Solution
Codespace file storage not restored Volume Snapshots not configured Configure Volume Snapshots before the next backup.
Restoration fails User deactivated Reactivate the user, then retry.
Item not found Retention period expired Restoration is not possible.
Use Case missing Associated Use Case deleted Use the --allow-deleted-use-cases flag. 
# Check service logs
kubectl logs -n <namespace> deployment/notebooks-data-retention
kubectl logs -n <namespace> deployment/notebooks-data-retention | grep -i "restoration"