Browse backup files
browse_restore_filesBrowse one directory inside a backup point: queues an asynchronous listing job, paginates results, and never restores files.
Instructions
Create a persisted asynchronous browse job to list one directory inside a backup point. This queues worker activity and stores the listing result; it does not restore files, change backup contents or the running server, or charge the account. Start at the backup root by passing only backupPointId. To open a subdirectory, pass sourceBrowseId plus the directoryEntryId of a type=directory entry from that result; filesystem paths are never accepted. A directory can hold an enormous number of files, so the server selects pages of 200 or 1,000 entries: while result.nextOffset is non-null, call again with the same sourceBrowseId and directoryEntryId and offset set to result.nextOffset. Use result.pageSize rather than assuming 200 when moving backwards. When nextOffset is null the listing cannot be paged further even if truncated is true — that is a capped scan; check result.listingStatus: 'complete' means the folder was read end to end, 'partial' means the listing is a bounded lower-bound slice, so never present it as the whole folder. Optionally pass filter to search entry NAMES in that one directory (substring, case-insensitive, never recursive) — but only when list_restore_file_points reported searchAvailable=true, otherwise this tool refuses rather than silently returning an unfiltered listing. The call is asynchronous: it returns a browse id in a pending state, and you must poll get_restore_file_browse until state is succeeded. Requires services:read and, because it is a POST, an API key that permits write operations plus an idempotencyKey.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Case-insensitive substring matched against entry NAMES in the browsed directory only. It never matches full paths and never searches subdirectories. Requires node search capability; check searchAvailable from list_restore_file_points first. | |
| offset | No | Copy a non-null result.nextOffset to page further through the SAME directory (a null nextOffset means the listing cannot be paged further). Must be 0 (or omitted) when starting a root listing or entering a directory. | |
| orderNo | Yes | Tenant-owned service order number: 1-64 ASCII letters, digits or hyphens, e.g. VP12345 or VP12345-1 | |
| backupPointId | Yes | Backup point ID returned by list_restore_file_points | |
| idempotencyKey | Yes | Client-global unique key for this exact browse request; reuse it only to replay the same request. | |
| sourceBrowseId | No | Browse id of the succeeded listing the directory entry came from. Omit to list the backup root. | |
| directoryEntryId | No | Opaque id of a type=directory entry from the source browse result. Filesystem paths are never accepted. |