S3 Glacier Storage Classes via S3 API

There are two ways to reach "Glacier" on AWS, and they are easy to confuse. The old way is a standalone service - Glacier Vaults, archives, and jobs, with its own API. The modern way is far simpler: Glacier is just a set of S3 storage classes you use through the S3 API you already know.

This page is about the modern way. You write objects into GLACIER_IR, GLACIER, or DEEP_ARCHIVE with put_object, and you read them back with restore_object plus get_object. Same bucket, same keys, same client. Reach for the Vault API only when maintaining an existing Vault workload.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
# Write an object straight into an archival storage class.
s3.put_object(
    Bucket="my-bucket",
    Key="archive/report.pdf",
    Body=b"...bytes...",
    StorageClass="GLACIER",   # GLACIER_IR | GLACIER | DEEP_ARCHIVE
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
// Write an object straight into an archival storage class.
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "archive/report.pdf",
  Body: Buffer.from("...bytes..."),
  StorageClass: "GLACIER",   // GLACIER_IR | GLACIER | DEEP_ARCHIVE
}));

When to reach for this:

• Archiving new data on AWS - the S3 API is the recommended path for all new workloads.
• Keeping backups, logs, media, or compliance records that are rarely read.
• Wanting archival storage to sit in the same bucket, keys, and IAM model as your live data.
• Integrating archival with S3 lifecycle rules, events, and Storage Lens.

Working Example

Write an object to DEEP_ARCHIVE, confirm its class, then restore it and read it back once the restore completes.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
bucket, key = "my-bucket", "archive/2019-ledger.parquet"
 
# 1. Archive the object.
s3.put_object(Bucket=bucket, Key=key, Body=b"...bytes...", StorageClass="DEEP_ARCHIVE")
 
# 2. Confirm the storage class without downloading.
head = s3.head_object(Bucket=bucket, Key=key)
print("class:", head.get("StorageClass", "STANDARD"))   # DEEP_ARCHIVE
 
# 3. Start a restore - creates a temporary readable copy for 1 day.
s3.restore_object(
    Bucket=bucket, Key=key,
    RestoreRequest={"Days": 1, "GlacierJobParameters": {"Tier": "Standard"}},
)
 
# 4. Later, once head_object shows ongoing-request="false", read it.
head = s3.head_object(Bucket=bucket, Key=key)
if 'ongoing-request="false"' in head.get("Restore", ""):
    body = s3.get_object(Bucket=bucket, Key=key)["Body"].read()
    print("restored:", len(body), "bytes")

// --- TypeScript (AWS SDK v3) ---
import {
  S3Client, PutObjectCommand, HeadObjectCommand, RestoreObjectCommand, GetObjectCommand,
} from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const Bucket = "my-bucket", Key = "archive/2019-ledger.parquet";
 
// 1. Archive the object.
await s3.send(new PutObjectCommand({ Bucket, Key, Body: Buffer.from("...bytes..."), StorageClass: "DEEP_ARCHIVE" }));
 
// 2. Confirm the storage class without downloading.
let head = await s3.send(new HeadObjectCommand({ Bucket, Key }));
console.log("class:", head.StorageClass ?? "STANDARD");   // DEEP_ARCHIVE
 
// 3. Start a restore - creates a temporary readable copy for 1 day.
await s3.send(new RestoreObjectCommand({
  Bucket, Key,
  RestoreRequest: { Days: 1, GlacierJobParameters: { Tier: "Standard" } },
}));
 
// 4. Later, once head shows ongoing-request="false", read it.
head = await s3.send(new HeadObjectCommand({ Bucket, Key }));
if ((head.Restore ?? "").includes('ongoing-request="false"')) {
  const obj = await s3.send(new GetObjectCommand({ Bucket, Key }));
  console.log("restored:", (await obj.Body!.transformToByteArray()).length, "bytes");
}

What this demonstrates:

• One S3 client does the whole flow - put, head, restore, get - with no separate Glacier client.
• head_object reports the class and, after a restore, the Restore header state.
• restore_object starts an asynchronous job; step 4 only succeeds once it finishes hours later.
• DEEP_ARCHIVE cannot be read directly - skipping the restore would raise InvalidObjectState.

Deep Dive

The Three Classes and How They Read

GLACIER_IR behaves like any warm class on read. The other two are offline until a restore stages a temporary copy.

Writing Into a Class

You set StorageClass on put_object, on copy_object (to re-tier an existing object in place), and on multipart uploads via create_multipart_upload. The value is just a string - GLACIER_IR, GLACIER, or DEEP_ARCHIVE. The object keeps its key and bucket; only its storage tier changes.

Restoring a Cold Object

restore_object takes a RestoreRequest with two parts: Days, how long the temporary readable copy should live, and GlacierJobParameters.Tier, which retrieval speed to buy (Expedited, Standard, or Bulk). The call returns quickly - it queues a job. When the job finishes, the object is readable via get_object until the copy's expiry-date, after which it goes cold again without changing storage class.

Watching the Restore State

head_object (or get_object_attributes) returns a Restore header once a restore exists:

• ongoing-request="true" - the restore job is still running.
• ongoing-request="false", expiry-date="..." - the copy is ready and expires at that date.

Polling this works for scripts, but the production-grade pattern is an S3 event notification on s3:ObjectRestore:Completed, so your code reacts instead of looping.

Why This Over the Vault API

The standalone Glacier Vault service predates these storage classes. It has its own vaults, archive ids, and job model, and it does not share S3's bucket, key, lifecycle, or event ecosystem. AWS positions S3 Glacier storage classes as the path forward. New work should use the S3 API; the Vault API is legacy, covered on its own page only for existing deployments.

Gotchas

• Reading GLACIER or DEEP_ARCHIVE without restoring - a bare get_object fails with InvalidObjectState. Fix: call restore_object first and wait for the restore to complete before get_object.
• Expecting restore to be synchronous - restore_object returns immediately but the data is not ready for minutes to hours. Fix: poll the Restore header or subscribe to an ObjectRestore:Completed event.
• Restoring twice - a second restore_object while one is in progress raises RestoreAlreadyInProgress. Fix: check the Restore header before issuing a new restore.
• Assuming Expedited works for Deep Archive - it does not; only Standard and Bulk apply there. Fix: use Standard or Bulk tiers for DEEP_ARCHIVE.
• Deleting before the minimum duration - GLACIER/GLACIER_IR bill a 90-day minimum, DEEP_ARCHIVE 180 days, even if you delete early. Fix: only archive data you expect to keep past the minimum.
• Confusing the class with the Vault service - "Glacier" the storage class and "Glacier" the Vault API are different things with different SDK clients. Fix: use the S3 client and storage classes for new work.

Alternatives

FAQs

Related

• Archival Storage Basics - the everyday put, head, restore, and get operations.
• Retrieval Tiers: Expedited, Standard & Bulk - choosing restore speed and cost.
• Legacy Glacier Vaults & Archive Retrieval Jobs - the older API this page replaces.
• Automating Archive Lifecycle Transitions - tiering into these classes automatically.

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