How to Get the Total Size of a Cloudflare R2 Bucket via the API

When managing object storage in Cloudflare R2, a common need is to find out how much space your bucket is using. While R2 integrates with many S3-compatible tools, it’s important to note that its compatibility isn’t complete — some AWS S3 APIs and features aren’t available. One of those conveniences is a direct way to query the total size of a bucket, which isn't obtained in the same way as you do in Amazon.

Instead, CloudFlare offers an endpoint in its REST API to obtain this information. In this short article, I will explain to you how to easily get the size of a bucket in CloudFlare R2 through their API.

What is CloudFlare R2

Cloudflare R2 is Cloudflare's object storage service, designed as an alternative to Amazon S3 (Simple Storage Service), but with no egress fees, which makes it a solid choice for developers who want to use buckets without spending a lot of money.

1. Set Up Your API Credentials

To obtain the total size of your buckets with CloudFlare's API, you will need:

1. Your account ID.
2. The name of the bucket.
3. An access token

The account ID of your CloudFlare account can be easily obtained from the homepage dashboard:

Now for the access token, access the API Tokens section in the R2 menu, and create a new API Token that allows you to read the information of your buckets:

The token that you obtain from filling this form can be used as a Bearer token in the API request to obtain the data that we need.

2. Prepare your API request

Unlike AWS S3, Cloudflare R2 provides its own native API endpoint for retrieving bucket usage statistics. This endpoint returns detailed information about your bucket’s total storage, object count, and metadata usage — without the need to iterate over every object.

To fetch this data, you’ll make a simple authenticated request to the R2 API using your account ID, bucket name, and a valid API token with R2 read permissions.

Here’s an example using curl:

curl --location 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/r2/buckets/{BUCKET_NAME}/usage' --header 'Authorization: Bearer {YOUR-TOKEN}'

This API call returns a JSON response with details about your bucket’s usage. A typical response looks like this:

{
    "success": true,
    "errors": [],
    "messages": [],
    "result": {
        "end": "2025-10-10T22:30:00.000Z",
        "payloadSize": "345397577129",
        "metadataSize": "4770042",
        "objectCount": "147014",
        "uploadCount": "0",
        "infrequentAccessPayloadSize": "0",
        "infrequentAccessMetadataSize": "0",
        "infrequentAccessObjectCount": "0",
        "infrequentAccessUploadCount": "0"
    }
}

Each property represents a specific metric:

• payloadSize — The total size (in bytes) of all objects stored in the bucket.

• metadataSize — The total size of associated metadata.

• objectCount — The total number of objects stored.

• uploadCount — Number of uploads during the reporting period.

• end — The timestamp marking when the usage data snapshot was generated.

Retrieving the size of a Cloudflare R2 bucket doesn't have to be complicated. Even though R2 isn’t fully S3-compatible, Cloudflare's native /usage API endpoint provides a straightforward way to access accurate and up-to-date metrics about your storage consumption. With a single authenticated request, you can obtain details like total payload size, metadata size, and object count — data that can be easily integrated into monitoring scripts, dashboards, or automation workflows.

By understanding how to interact directly with the R2 API, you gain more flexibility and transparency over your storage usage, without relying on third-party tools or manual calculations. This approach ensures that you stay in control of your resources — an essential step for efficient and cost-effective cloud storage management.