Archival Storage Basics

The modern way to archive on AWS is not a separate service - it is an S3 storage class. You write an object into GLACIER_IR, GLACIER, or DEEP_ARCHIVE with the same put_object you already know, and the object still lives in your bucket under its normal key.

This page walks the everyday archival operations: writing straight into a cold class, checking an object's class and restore state, restoring a GLACIER object so you can read it, and reading a GLACIER_IR object with no restore at all. Every example mirrors between boto3 and the AWS SDK v3.

Prerequisites

• Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-s3 (Node.js 18+).
• Credentials configured via aws configure, environment variables, or an IAM role - the SDK resolves them automatically.
• An existing bucket. These examples assume a bucket named my-bucket in us-east-1.
• IAM permission for s3:PutObject, s3:GetObject, s3:RestoreObject, and s3:GetObjectAttributes on that bucket.

Basic Examples

1. Upload Straight Into an Archival Class

Pass StorageClass to put_object and the object lands in that class immediately - no lifecycle rule, no waiting.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
s3.put_object(
    Bucket="my-bucket",
    Key="archive/2020-invoices.zip",
    Body=b"...bytes...",
    StorageClass="DEEP_ARCHIVE",   # cheapest storage, slowest to read
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "archive/2020-invoices.zip",
  Body: Buffer.from("...bytes..."),
  StorageClass: "DEEP_ARCHIVE",   // cheapest storage, slowest to read
}));

• Valid archival values are GLACIER_IR, GLACIER, and DEEP_ARCHIVE; the default is STANDARD.
• The object keeps its normal key and lives in the same bucket - archival is a property, not a location.
• Writing directly is best for data you already know is cold; use lifecycle rules to tier data that starts warm.
• DEEP_ARCHIVE and GLACIER objects cannot be read back until you restore them.

Related: Automating Archive Lifecycle Transitions - tier objects automatically instead of writing the class by hand.

2. Check an Object's Storage Class

head_object returns the storage class without downloading the body. Standard objects report no StorageClass field (it defaults to Standard); archival objects name their class.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
head = s3.head_object(Bucket="my-bucket", Key="archive/2020-invoices.zip")
print(head.get("StorageClass", "STANDARD"))   # e.g. "DEEP_ARCHIVE"

// --- TypeScript (AWS SDK v3) ---
import { S3Client, HeadObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const head = await s3.send(new HeadObjectCommand({ Bucket: "my-bucket", Key: "archive/2020-invoices.zip" }));
console.log(head.StorageClass ?? "STANDARD");   // e.g. "DEEP_ARCHIVE"

• HeadObject transfers headers only, so it is fast and cheap for inspection.
• A STANDARD object omits the StorageClass field entirely - default it yourself.
• The same call later shows the Restore header once you have requested a restore.
• Use this before a get_object to decide whether the object needs restoring first.

3. Read a GLACIER_IR Object Instantly

Glacier Instant Retrieval needs no restore. A get_object works exactly as it does for Standard, just at a lower storage price.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
# The object was written with StorageClass="GLACIER_IR" - no restore needed.
obj = s3.get_object(Bucket="my-bucket", Key="archive/thumbnail.jpg")
data = obj["Body"].read()
print(len(data), "bytes")

// --- TypeScript (AWS SDK v3) ---
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
// The object was written with StorageClass "GLACIER_IR" - no restore needed.
const obj = await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "archive/thumbnail.jpg" }));
const data = await obj.Body!.transformToByteArray();
console.log(data.length, "bytes");

• GLACIER_IR is the only archival class you can get directly, in milliseconds.
• Trying the same get_object on a GLACIER or DEEP_ARCHIVE object raises InvalidObjectState.
• Use GLACIER_IR for archives you rarely read but must read instantly when you do.
• Storage is cheaper than Standard-IA, but per-GB retrieval fees are higher, so read sparingly.

Intermediate Examples

4. Restore a Cold Object So You Can Read It

GLACIER and DEEP_ARCHIVE objects must be restored first. restore_object asks S3 to create a temporary readable copy that lasts for Days, using the retrieval Tier you pick.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
s3.restore_object(
    Bucket="my-bucket",
    Key="archive/2020-invoices.zip",
    RestoreRequest={
        "Days": 2,                                   # copy stays readable 2 days
        "GlacierJobParameters": {"Tier": "Standard"},  # Expedited | Standard | Bulk
    },
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client, RestoreObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
await s3.send(new RestoreObjectCommand({
  Bucket: "my-bucket",
  Key: "archive/2020-invoices.zip",
  RestoreRequest: {
    Days: 2,                                       // copy stays readable 2 days
    GlacierJobParameters: { Tier: "Standard" },    // Expedited | Standard | Bulk
  },
}));

• restore_object returns almost immediately - it starts a job, it does not wait for it.
• Days sets how long the temporary readable copy lives before it expires.
• Tier trades cost for speed: Expedited (Flexible only) minutes, Standard hours, Bulk longest and cheapest.
• Calling restore again while one is in progress raises RestoreAlreadyInProgress.

5. Poll the Restore State, Then Download

After a restore starts, head_object reports a Restore header. It reads ongoing-request="true" while the job runs, then flips to a completed form with an expiry date - at which point get_object works.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
head = s3.head_object(Bucket="my-bucket", Key="archive/2020-invoices.zip")
restore = head.get("Restore", "")
if 'ongoing-request="false"' in restore:
    obj = s3.get_object(Bucket="my-bucket", Key="archive/2020-invoices.zip")
    print(len(obj["Body"].read()), "bytes ready")
else:
    print("still restoring:", restore)   # ongoing-request="true"

// --- TypeScript (AWS SDK v3) ---
import { S3Client, HeadObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const head = await s3.send(new HeadObjectCommand({ Bucket: "my-bucket", Key: "archive/2020-invoices.zip" }));
const restore = head.Restore ?? "";
if (restore.includes('ongoing-request="false"')) {
  const obj = await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "archive/2020-invoices.zip" }));
  console.log((await obj.Body!.transformToByteArray()).length, "bytes ready");
} else {
  console.log("still restoring:", restore);   // ongoing-request="true"
}

• The Restore header is absent until you have issued a restore for the object.
• ongoing-request="true" means the job is still running; do not get yet.
• When it reads ongoing-request="false", an expiry-date shows when the readable copy disappears.
• Polling works, but an S3 event on restore completion is cheaper than a poll loop - prefer it in production.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).