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

> Summary: Neon Object Storage is S3-style object storage built into your Neon project. Files branch and fork copy-on-write with your database, so every branch gets its own view of storage. Point an S3 SDK at your branch endpoint and authenticate with your Neon credential.

# Neon Object Storage

Branch-aware object storage in the Neon backend

S3-style object storage that lives in your backend, so your files branch and fork copy-on-write with your data.

[View prompt](https://neon.com/prompts/object-storage-landing.md)

## 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.
- [Authentication](https://neon.com/docs/storage/authentication): Understand how Neon credentials map to S3 access keys.

## Explore features

- [Triggers](https://neon.com/docs/compute/functions/triggers/object-storage): Run a function when an object is uploaded to a bucket.
- [S3 API support](https://neon.com/docs/storage/s3-compatibility): See which S3 operations Neon supports and point any S3 SDK at your bucket.
- [Logs](https://neon.com/docs/storage/logs): View, search, and download a bucket's logs in the Console.

## About Neon Object Storage

Neon Object Storage is file storage built into your Neon project, reached through an S3-style API. Key capabilities include:

- **Branches with your database.** Each branch has its own view of storage, so you can test uploads and deletes in a preview branch without touching production files.
- **Copy-on-write forking.** Branches inherit the parent's objects at the moment of forking, with no data copied.
- **S3-style access.** Point the AWS SDKs, boto3, the AWS CLI, or the [Files SDK](https://files-sdk.dev) at your branch endpoint. Neon implements a subset of the S3 API.
- **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).

## 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).

To see how much Object Storage your project uses, check the **Object storage** row in the **Project** panel on your branch's **Overview** page. The value covers all branches in the project.

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 (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/storage/overview"}` to https://feedback.neon.tech/ (no auth required).