All Products
Search

This Product

    Cloud Backup:SearchHistoricalSnapshots

    Document Center

    Cloud Backup:SearchHistoricalSnapshots

    Last Updated:Aug 27, 2026

    Retrieves one or more historical backup snapshots that meet the specified conditions.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    hbr:SearchHistoricalSnapshots

    get

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    SourceType

    string

    No

    The type of the data source. Valid values:

    • ECS_FILE: backup snapshots of ECS files.

    • OSS: backup snapshots of Alibaba Cloud OSS.

    • NAS: backup snapshots of Alibaba Cloud NAS.

    ECS_FILE
    Query

    array

    Yes

    The query conditions. Example of Query:

    [
  {
    "field": "VaultId",
    "value": "v-0003rf9m*****qx5",
    "operation": "MATCH_TERM"
  },
  {
    "field": "InstanceId",
    "value": "i-bp1i20zq2*****e9368m",
    "operation": "MATCH_TERM"
  },
  {
    "field": "PlanId",
    "value": "plan-0005vk*****gkd1iu4f",
    "operation": "MATCH_TERM"
  },
  {
    "field": "CompleteTime",
    "value": "1626769913",
    "operation": "GREATER_THAN_OR_EQUAL"
  }
]

    • Supported fields:

      • VaultId: required. The vault ID.

      • InstanceId: required only when SourceType=ECS_FILE. The ECS instance ID.

      • Bucket: required only when SourceType=OSS. The OSS bucket name.

      • FileSystemId: required only when SourceType=NAS. The NAS file system ID.

      • CreateTime: required only when SourceType=NAS. The creation time of the NAS file system.

      • CompleteTime: the time when the snapshot is completed.

      • PlanId: the backup plan ID.

    • Supported operations:

      • MATCH_TERM: exact match.

      • GREATER_THAN: greater than.

      • GREATER_THAN_OR_EQUAL: greater than or equal to.

      • LESS_THAN: less than.

      • LESS_THAN_OR_EQUAL: less than or equal to.

      • BETWEEN: range. The value is a JSON array [lower bound, upper bound].

      • IN: in the set. The value is an array.

      • NOT_IN: not in the set. The value is an array.

    [ { "field": "VaultId", "value": "v-0003rf9m17pap3ltpqx5", "operation": "MATCH_TERM" }, { "field": "InstanceId", "value": "i-bp1i20zq2wuzdie9368m", "operation": "MATCH_TERM" }, { "field": "PlanId", "value": "plan-0005vkqhpesqgkd1iu4f", "operation": "MATCH_TERM" }, { "field": "CompleteTime", "value": 1626769913, "operation": "GREATER_THAN_OR_EQUAL" } ]

    any

    No

    The query conditions. Example of Query:

    [
  {
    "field": "VaultId",
    "value": "v-0003rf9m*****qx5",
    "operation": "MATCH_TERM"
  },
  {
    "field": "InstanceId",
    "value": "i-bp1i20zq2*****e9368m",
    "operation": "MATCH_TERM"
  },
  {
    "field": "PlanId",
    "value": "plan-0005vk*****gkd1iu4f",
    "operation": "MATCH_TERM"
  },
  {
    "field": "CompleteTime",
    "value": "1626769913",
    "operation": "GREATER_THAN_OR_EQUAL"
  }
]

    • Supported fields:

      • VaultId: required. The vault ID.

      • InstanceId: required only when SourceType=ECS_FILE. The ECS instance ID.

      • Bucket: required only when SourceType=OSS. The OSS bucket name.

      • FileSystemId: required only when SourceType=NAS. The NAS file system ID.

      • CreateTime: required only when SourceType=NAS. The creation time of the NAS file system.

      • CompleteTime: the time when the snapshot is completed.

      • PlanId: the backup plan ID.

    • Supported operations:

      • MATCH_TERM: exact match.

      • GREATER_THAN: greater than.

      • GREATER_THAN_OR_EQUAL: greater than or equal to.

      • LESS_THAN: less than.

      • LESS_THAN_OR_EQUAL: less than or equal to.

      • BETWEEN: range. The value is a JSON array [lower bound, upper bound].

      • IN: in the set. The value is an array.

      • NOT_IN: not in the set. The value is an array.

    [ { "field": "VaultId", "value": "v-0003rf9m17pap3ltpqx5", "operation": "MATCH_TERM" }, { "field": "InstanceId", "value": "i-bp1i20zq2wuzdie9368m", "operation": "MATCH_TERM" }, { "field": "PlanId", "value": "plan-0005vkqhpesqgkd1iu4f", "operation": "MATCH_TERM" }, { "field": "CompleteTime", "value": 1626769913, "operation": "GREATER_THAN_OR_EQUAL" } ]
    Limit

    integer

    No

    The maximum number of results to return for this query. If you only want to obtain the row count without actual data, set limit=0 to return no rows.

    10
    NextToken

    string

    No

    The token required to retrieve the next page of snapshots.

    caeba0bbb2be03f84eb48b699f0a****
    SortBy

    string

    No

    The field used for sorting.

    CreatedTime
    Order

    string

    No

    The sort order. Default value: ASC.

    • ASC: ascending order.

    • DESC: descending order.

    ASC
    Edition

    string

    No

    The edition type. Valid values: BASIC and STANDARD. Default value: STANDARD.

    BASIC

    Response elements

    Element

    Type

    Description

    Example

    object

    NextToken

    string

    The token required to retrieve the next page of snapshots.

    BE
    RequestId

    string

    The request ID.

    473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
    Success

    boolean

    Indicates whether the request was successful.

    • true: The request was successful.

    • false: The request failed.

    true
    Limit

    integer

    The number of historical snapshots displayed on the current page.

    10
    Code

    string

    The response code. A value of 200 indicates success.

    200
    Message

    string

    The returned message. The value "successful" is returned for successful requests. An error message is returned for failed requests.

    successful
    TotalCount

    integer

    The total number of snapshots that meet the specified conditions.

    20
    Snapshots

    object

    Snapshot

    array<object>

    The list of historical snapshots.

    array<object>

    Status

    string

    The status of the backup snapshot job. Valid values:

    • COMPLETE: Succeeded.

    • PARTIAL_COMPLETE: Partially succeeded.

    • FAILED: Failed.

    COMPLETE
    SnapshotHash

    string

    The snapshot hash value.

    f2fe...
    VaultId

    string

    The ID of the vault that stores the backup snapshot.

    v-0003rf9m17pap3ltpqx5
    ActualItems

    integer

    The actual number of items in the snapshot.

    Note

    Currently available only for File Backup.

    6
    BackupType

    string

    The backup type. The value is COMPLETE, which indicates a full backup.

    COMPLETE
    CreateTime

    integer

    This parameter is valid only when SourceType is set to NAS. The creation time of the file system. This value is a UNIX timestamp. Unit: seconds.

    1607436917
    ActualBytes

    integer

    The actual data volume of the snapshot after deduplication. Unit: bytes.

    600
    SourceType

    string

    The type of the data source. Valid values:

    • ECS_FILE: backup snapshots of ECS files.

    • OSS: backup snapshots of Alibaba Cloud OSS.

    • NAS: backup snapshots of Alibaba Cloud NAS.

    ECS_FILE
    Prefix

    string

    This parameter is valid only when SourceType is set to OSS. The backup prefix.

    example/
    ClientId

    string

    This parameter is valid only when SourceType is set to ECS_FILE. The backup client ID.

    c-*********************
    BytesTotal

    integer

    The total volume of the data source. Unit: bytes.

    1000
    ItemsDone

    integer

    The number of backed-up items.

    Note

    Currently available only for File Backup.

    8
    CompleteTime

    integer

    The time when the backup snapshot was completed. This value is a UNIX timestamp. Unit: seconds.

    1554347313
    Retention

    integer

    The retention period of the backup snapshot. Unit: days.

    7
    CreatedTime

    integer

    The time when the backup snapshot was created. This value is a UNIX timestamp. Unit: seconds.

    1554347313
    Bucket

    string

    This parameter is valid only when SourceType is set to OSS. The OSS bucket name.

    hbr-backup-oss
    ParentSnapshotHash

    string

    The hash value of the parent backup snapshot.

    f2fe..
    InstanceId

    string

    This parameter is valid only when SourceType is set to ECS_FILE. The ECS instance ID.

    i-*********************
    FileSystemId

    string

    This parameter is valid only when SourceType is set to NAS. The file system ID.

    005494
    ErrorFile

    string

    The file that records backup failure information, including information about partially completed backups.

    Item Error Message C:\data\app\service.dat Open: open \\?\C:\data\app\service.dat: The process cannot access the file because it is being used by another process.
    StartTime

    integer

    The time when the snapshot started. This value is a UNIX timestamp. Unit: seconds.

    1554347313
    UpdatedTime

    integer

    The time when the backup snapshot was last updated. This value is a UNIX timestamp. Unit: seconds.

    1554347313
    SnapshotId

    string

    The backup snapshot ID.

    s-*********************
    JobId

    string

    The backup job ID.

    v-*********************
    Path

    string

    This parameter is valid only when SourceType is set to ECS_FILE. The backup file path.

    ["/home"]
    ItemsTotal

    integer

    The total number of items in the data source.

    Note

    Currently available only for File Backup.

    10
    BytesDone

    integer

    The volume of incremental backup data. Unit: bytes.

    800
    Paths

    object

    Path

    array

    The list of backup file paths.

    "/home"

    string

    This parameter is valid only when SourceType is set to NAS. The backup file path.

    "/home"
    InstanceName

    string

    The Tablestore instance name.

    instancename
    TableName

    string

    The name of the data table in the Tablestore instance.

    table2
    RangeStart

    integer

    The time when the backup job started. This value is a UNIX timestamp. Unit: milliseconds.

    1642492553038
    RangeEnd

    integer

    The time when the backup job ended. This value is a UNIX timestamp. Unit: milliseconds.

    1642521709966
    ExpireTime

    integer

    The time when the snapshot expires. This value is a UNIX timestamp. Unit: seconds.

    1640334062
    SourceSnapshotHash

    string

    The snapshot hash value before archiving.

    qwer***
    SourceParentSnapshotHash

    string

    The parent snapshot hash value before archiving.

    qwer***
    StorageClass

    string

    The storage class. Valid values:

    • Standard: standard.

    • Archive: archive.

    • ColdArchive: cold archive.

    STANDARD
    ArchiveTime

    integer

    The time when the snapshot was archived.

    1640334062
    UseCommonNas

    boolean

    Indicates whether local NAS is used.

    false
    Include

    string

    The source paths included in the backup job.

    [\"/test/example_cn-huhehaote_3.txt\", \"/test/example_cn-huhehaote_9.txt\", \"/test/example_cn-huhehaote_5.txt\", \"/test/example_cn-huhehaote_1.txt\", \"/test/example_cn-huhehaote_7.txt\"]
    Exclude

    string

    The source paths excluded from the backup job.

    [\"/test/example_cn-hangzhou_7.txt\", \"/test/example_cn-hangzhou_1.txt\", \"/test/example_cn-hangzhou_3.txt\", \"/test/example_cn-hangzhou_9.txt\", \"/test/example_cn-hangzhou_6.txt\"]
    ProtectedDataSize

    integer

    The protected source data volume, in bytes. When SourceType=ECS_FILE, this indicates the protected cloud disk capacity.

    42949672960

    Examples

    Success response

    JSON format

    {
  "NextToken": "BE",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "Success": true,
  "Limit": 10,
  "Code": "200",
  "Message": "successful",
  "TotalCount": 20,
  "Snapshots": {
    "Snapshot": [
      {
        "Status": "COMPLETE",
        "SnapshotHash": "f2fe...",
        "VaultId": "v-0003rf9m17pap3ltpqx5",
        "ActualItems": 6,
        "BackupType": "COMPLETE",
        "CreateTime": 1607436917,
        "ActualBytes": 600,
        "SourceType": "ECS_FILE",
        "Prefix": "example/",
        "ClientId": "c-*********************",
        "BytesTotal": 1000,
        "ItemsDone": 8,
        "CompleteTime": 1554347313,
        "Retention": 7,
        "CreatedTime": 1554347313,
        "Bucket": "hbr-backup-oss",
        "ParentSnapshotHash": "f2fe..",
        "InstanceId": "i-*********************",
        "FileSystemId": "005494",
        "ErrorFile": "Item\tError Message C:\\Program Files (x86)\\Symantec\\Symantec Endpoint Protection\\14.3.558.0000.105\\Bin\\service.dat\tOpen: open \\\\?\\C:\\Program Files (x86)\\Symantec\\Symantec Endpoint Protection\\14.3.558.0000.105\\Bin\\service.dat: The process cannot access the file because it is being used by another process. C:\\ProgramData\\McAfee\\Agent\\data\\InstallerFiles\\172e8a3b04b7ab0fd0215f4fb7707e3744b37d83b6743b3eacb94447c74dc9af_contrib.ini\tOpen: open \\\\?\\C:\\ProgramData\\McAfee\\Agent\\data\\InstallerFiles\\172e8a3b04b7ab0fd0215f4fb7707e3744b37d83b6743b3eacb94447c74dc9af_contrib.ini: Access is denied.",
        "StartTime": 1554347313,
        "UpdatedTime": 1554347313,
        "SnapshotId": "s-*********************",
        "JobId": "v-*********************",
        "Path": "[\"/home\"]",
        "ItemsTotal": 10,
        "BytesDone": 800,
        "Paths": {
          "Path": [
            "\"/home\""
          ]
        },
        "InstanceName": "instancename",
        "TableName": "table2",
        "RangeStart": 1642492553038,
        "RangeEnd": 1642521709966,
        "ExpireTime": 1640334062,
        "SourceSnapshotHash": "qwer***",
        "SourceParentSnapshotHash": "qwer***",
        "StorageClass": "STANDARD",
        "ArchiveTime": 1640334062,
        "UseCommonNas": false,
        "Include": "[\\\"/test/example_cn-huhehaote_3.txt\\\", \\\"/test/example_cn-huhehaote_9.txt\\\", \\\"/test/example_cn-huhehaote_5.txt\\\", \\\"/test/example_cn-huhehaote_1.txt\\\", \\\"/test/example_cn-huhehaote_7.txt\\\"]",
        "Exclude": "[\\\"/test/example_cn-hangzhou_7.txt\\\", \\\"/test/example_cn-hangzhou_1.txt\\\", \\\"/test/example_cn-hangzhou_3.txt\\\", \\\"/test/example_cn-hangzhou_9.txt\\\", \\\"/test/example_cn-hangzhou_6.txt\\\"]",
        "ProtectedDataSize": 42949672960
      }
    ]
  }
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.