Overview
The RenameObject API provides a simpler and more efficient alternative to copy-and-delete workflows. Key benefits include:- Atomic operation: No window where both keys exist simultaneously
- No data movement: Updates metadata only, avoiding copy latency and temporary storage duplication
- Metadata preservation: Encryption settings, storage billing tier, checksums, and other attributes are preserved
- Precondition support: ETag and time-based conditions guard against race conditions and accidental overwrites
Use cases
| Use case | Description |
|---|---|
| Checkpoint promotion | Rename temporary checkpoints to final names after training runs complete |
| Batch finalization | Move artifacts from staging prefixes to final locations after validation |
| Log rotation | Atomically “lock” time-based prefixes by renaming to finalized paths |
Limitations
- Same bucket only: cross-bucket rename is not supported
- Versioning not supported: buckets with versioning enabled or previously enabled cannot use RenameObject
- Single object per request: prefix-level rename must be implemented as client-side batches
Learn more
- See the Rename Objects guide for an end-to-end walkthrough with examples
- See the RenameObject API reference for S3 compatibility details
- See conditional writes (March 23, 2026) for the same precondition pattern on PutObject, CompleteMultipartUpload, and CopyObject