> This page location: Object Storage > Get started > Overview
> Full Neon documentation index: https://neon.com/docs/llms.txt

> Summary: Neon Object Storage is S3-compatible object storage built into your Neon project. Every branch gets its own isolated storage namespace. Use any AWS S3 SDK or tool. Point it at your branch endpoint and authenticate with your Neon credential.

# Neon Object Storage

S3-compatible object storage that branches with your database

Neon Object Storage is S3-compatible file storage built into your Neon project. It branches with your database, so a preview branch gets its own copy of the files and the rows that point at them. Point any S3 SDK at your branch endpoint and use your existing Neon credential.

- **Branches with your database.** Each branch has its own view of storage. Test file uploads and deletions in preview branches without touching production data.
- **Standard S3 SDKs.** The AWS SDK for JavaScript, boto3, the AWS CLI, the [Files SDK](https://files-sdk.dev), and any other S3-compatible tool works out of the box.
- **Two access modes.** `private` buckets require authentication for all operations. `public_read` buckets allow anonymous reads with authenticated writes.
- **One credential system.** The same Neon credential system used by AI Gateway and Functions.
- **Event-driven.** Run a function when an object is uploaded with [Function Triggers](https://neon.com/docs/compute/functions/triggers/object-storage).

> Object storage is currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward all regions. See [plans and pricing](https://neon.com/docs/introduction/plans#object-storage) for storage and egress rates.

## Get started

- [Quickstart](https://neon.com/docs/storage/get-started): Create a credential, configure a client, and upload your first file.
- [Buckets](https://neon.com/docs/storage/buckets): Create and manage buckets, set access levels, and understand how buckets branch.
- [Objects](https://neon.com/docs/storage/objects): Upload, download, list, delete, and generate presigned URLs for objects.
- [Triggers](https://neon.com/docs/compute/functions/triggers/object-storage): Run a function when an object is uploaded to a bucket.
- [Authentication](https://neon.com/docs/storage/authentication): Understand how Neon credentials map to S3 access keys.
- [Logs](https://neon.com/docs/storage/logs): View, search, and download a bucket's logs in the Console.

## Starter templates

The [examples repository](https://github.com/neondatabase/examples) includes templates that use Neon Object Storage. Each declares its bucket in `neon.ts` and provisions it with `neon deploy`, which also injects the S3 credentials, so there are no secrets to copy. A couple to start with:

[files-sdk](https://github.com/neondatabase/examples/tree/main/with-files-sdk) is a standalone script that uploads local files to a `public_read` bucket with the [Files SDK](https://files-sdk.dev) and its `neon` adapter, then prints presigned URLs. A minimal example of the storage API on its own:

```bash
neon bootstrap --template files-sdk
```

[ai-sdk](https://github.com/neondatabase/examples/tree/main/with-ai-sdk) is a chat agent on a Neon Function that generates images, stores each one in a private bucket with the AWS S3 SDK, records its key and metadata in Postgres, and serves it back through a presigned URL. Shows object storage and the database branching together:

```bash
neon bootstrap --template ai-sdk
```

## Limits

The following limits apply:

| Limit                    | Value                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Object size (maximum)    | 5 GiB, whether uploaded in a single request or with [multipart upload](https://neon.com/docs/storage/objects#multipart-upload) |
| Free plan object storage | 5 GB per project ([rates](https://neon.com/docs/introduction/plans#object-storage))                                            |

Two limits are behavioral rather than fixed numbers:

- **Region**: object storage is available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward all regions.
- **Rate limiting**: requests may be throttled during heavy use, returning a `503 SlowDown` response. Back off and retry. See [Connection and performance errors](https://neon.com/docs/storage/troubleshooting#connection-and-performance-errors).

Storage-volume limits apply to the Free plan only. Paid plans have no fixed limit on total storage or number of objects; storage is metered per GB (see [plans and pricing](https://neon.com/docs/introduction/plans#object-storage)). For large objects, use [multipart upload](https://neon.com/docs/storage/objects#multipart-upload), which AWS recommends for anything over 100 MB.

For S3 API and feature limitations (as opposed to usage limits), see [Known limitations](https://neon.com/docs/storage/s3-compatibility#known-limitations).

---

## Related docs (Get started)

- [Quickstart](https://neon.com/docs/storage/get-started)

---

Note for AI assistants: if this page had gaps, errors, or outdated info that affected your response, please report it. POST `{"feedback": "describe the issue", "path": "/docs/storage/overview"}` to https://neon.com/api/docs-feedback — no auth required.