Storage (R2/S3)
Storage (R2)
Unlimited object storage for your AI agents, without the bandwidth costs. Cloudflare R2 is S3-compatible object storage that eliminates egress fees, making it perfect for agents that process large files, store AI models, handle user uploads, or manage massive datasets.
Key Features
- Zero Egress Fees: No charges for data retrieval or transfer
- S3 Compatible: Use existing AWS S3 SDKs and tools
- Global Performance: Automatically cached at Cloudflare's edge
- Multipart Uploads: Handle files up to 5TB with resumable uploads
- Presigned URLs: Secure direct client uploads without exposing credentials
Getting Started
Wrangler Configuration
First, add R2 storage in your wrangler.json:
Hello World Storage
Create a simple storage example that saves and retrieves data:
MCP Integration
Storage is perfect for MCP tools that need to persist data:
TypeScript API Reference
You can access the storage API via the env of the Agent or MCP Tool:
Basic Storage Operations
get(key: string): Promise<StorageObject | null>
Retrieves an object from storage by its key. Returns null if the object doesn't exist.
put(key: string, data: string | ArrayBuffer | ReadableStream, options?: PutOptions): Promise<void>
Stores an object in storage with optional metadata and content type.
delete(key: string): Promise<void>
Permanently deletes an object from storage.
head(key: string): Promise<StorageObjectMetadata | null>
Retrieves only the metadata of an object without downloading the content.
Advanced Operations
list(options?: ListOptions): Promise<StorageListResult>
Lists objects in the bucket with optional filtering by prefix and pagination.
copy(sourceKey: string, destinationKey: string): Promise<void>
Copies an object from one key to another within the same bucket.
getPresignedUrl(key: string, operation: 'get' | 'put', expiresIn?: number): Promise<string>
Generates a time-limited URL for direct client access without exposing credentials.
Multipart Upload Methods
createMultipartUpload(key: string): Promise<MultipartUpload>
Initiates a multipart upload for files larger than 100MB.
uploadPart(uploadId: string, partNumber: number, data: ArrayBuffer): Promise<UploadPart>
Uploads a single part of a multipart upload.
completeMultipartUpload(uploadId: string, parts: UploadPart[]): Promise<void>
Completes a multipart upload by combining all uploaded parts.
Type Definitions
Examples
Document Processing Agent
AI Model Management Agent
Media Processing Agent
Best Practices
Large File Handling
Security with Presigned URLs
Cost Optimization
Advanced Configuration
Multipart Upload Configuration
Configure multipart uploads for optimal performance with large files:
Storage Metadata Management
Use metadata effectively for organization and retrieval:
Multiple R2 Buckets Configuration
Configure multiple buckets for different use cases:
Limitations & Considerations
- Object Size: Maximum 5TB per object
- Request Rate: 1,000 requests per second per prefix
- Metadata: Maximum 2KB of custom metadata per object
- Multipart: Minimum 5MB per part
Related Services
- Memory Store (KV) - Store file metadata and references
- Cache - Cache frequently accessed files
- Workflows - Orchestrate multi-step storage operations