All Products
Search

This Product

    Object Storage Service:restore-object

    Document Center

    Object Storage Service:restore-object

    Last Updated:Mar 19, 2026

    Use restore-object to restore Archive, Cold Archive, or Deep Cold Archive objects before reading them.

    Prerequisites

    Before you begin, ensure that you have:

    • An Archive, Cold Archive, or Deep Cold Archive object to restore. This command does not apply to Standard or Infrequent Access (IA) objects.

    • The oss:RestoreObject permission (required for Resource Access Management (RAM) users and Security Token Service (STS) token users; Alibaba Cloud account owners have this permission by default)

    How it works

    All restore operations are asynchronous. The object moves through the following states:

    1. Frozen — the initial state of an archived object; not accessible.

    2. Restoring — OSS is processing the restore request.

    3. Restored — the object is accessible. To extend this state, submit another restore request before it expires. The total duration cannot exceed the maximum for the storage class.

    4. Frozen again — after the restored state expires, the object returns to the frozen state. Its storage class does not change.

    Syntax

    ossutil api restore-object --bucket <value> --key <value> [flags]

    Required parameters:

    ParameterTypeDescription
    --bucketstringThe name of the bucket.
    --keystringThe full path of the object.

    Optional parameters:

    ParameterTypeDescription
    --restore-requeststringThe restore request body. Supports XML and JSON. Use the file:// prefix to read from a local file.
    --version-idstringThe version ID of the object to restore.
    For global command-line options supported by ossutil, see Supported global command-line options.

    --restore-request format

    The --restore-request parameter accepts XML or JSON. Specify it inline or read it from a file using the file:// prefix.

    XML syntax:

    <RestoreRequest>
  <Days>integer</Days>
  <JobParameters>
    <Tier>string</Tier>
  </JobParameters>
</RestoreRequest>

    JSON syntax:

    {
  "Days": integer,
  "JobParameters": {
    "Tier": "string"
  }
}

    Days sets how long the object stays in the restored state. Tier sets the retrieval priority for Cold Archive and Deep Cold Archive objects — not required for Archive. The table below shows the restoration time for each tier.

    Storage classTierRestoration time
    Archive—~1 minute
    Cold ArchiveExpeditedWithin 1 hour
    Cold ArchiveStandard2–5 hours
    Cold ArchiveBulk5–12 hours
    Deep Cold ArchiveExpeditedWithin 12 hours
    Deep Cold ArchiveStandardWithin 48 hours
    These are reference values. Actual restoration time may vary.

    Restoration quotas

    OSS applies per-account, per-region restore quotas. These are reference values.

    Storage classQuota
    Cold ArchiveAverage 500 objects/sec; 100 TB–120 TB/day (across all three tiers)
    Deep Cold ArchiveAverage 100 objects/sec; 10 TB–15 TB/day (across both tiers)
    Restore requests are still accepted after the quota is exceeded. The request is queued, and the actual restoration time may be longer than the expected time for the selected tier.

    Duration of the restored state

    Storage classDuration
    Archive1–7 days
    Cold Archive1–365 days
    Deep Cold Archive1–365 days

    Billing

    All restore operations incur storage fees, data retrieval fees, and request fees.

    • Storage fees: Calculated based on the storage class throughout and after restoration. See Storage fees.

    • Data retrieval fees: Incurred for all storage classes. See Data processing fees.

    • Request fees:

      • Archive: PUT request fees.

      • Cold Archive and Deep Cold Archive: retrieval request fees.

      • See Request fees.

    • Temporary storage fees (Cold Archive and Deep Cold Archive only): OSS creates a temporary replica to allow access during the restored state. This replica is billed at the Standard storage class rate until the restored state expires. See Temporary storage fees.

    Examples

    Restore an Archive object

    Archive objects require only the Days parameter — no Tier needed. The following examples restore exampleobject from examplebucket for 2 days.

    Inline JSON (quickest):

    ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request "{\"Days\":\"2\"}"

    JSON file (restore-request.json):

    {
  "Days": "2"
}
    ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.json

    XML file (restore-request.xml):

    <?xml version="1.0" encoding="UTF-8"?>
<RestoreRequest>
  <Days>2</Days>
</RestoreRequest>
    ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.xml

    Restore a Cold Archive or Deep Cold Archive object

    Cold Archive and Deep Cold Archive objects require a Tier value to set the retrieval priority. The following examples restore exampleobject from examplebucket for 2 days using Standard retrieval.

    Inline JSON:

    ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request "{\"Days\":\"2\",\"JobParameters\":{\"Tier\":\"Standard\"}}"

    JSON file (restore-request.json):

    {
  "Days": "2",
  "JobParameters": {
    "Tier": "Standard"
  }
}
    ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.json

    XML file (restore-request.xml):

    <?xml version="1.0" encoding="UTF-8"?>
<RestoreRequest>
  <Days>2</Days>
  <JobParameters>
    <Tier>Standard</Tier>
  </JobParameters>
</RestoreRequest>
    ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.xml

    What's next