Object Storage

Overview

Cosmoner object storage provides S3-compatible buckets. Each bucket runs on a prepaid tier that includes storage, egress, and request allowances. Usage above the allowances is billed as overage, and you can set a monthly limit on it for each bucket.

Tiers

Egress and requests are per billing period. All tiers run on the same storage; the difference is in the included allowances. A bucket keeps the allowances its tier had when it was created or last changed tier.

Choosing a Tier

Consider all three dimensions — storage, egress, and requests — when selecting a tier. A small dataset with high read traffic may need a higher tier than a large archive that is rarely accessed.

• Starter — Development, prototyping, or low-traffic assets (marketing sites, small apps).
• Growth — Production workloads with moderate traffic. Good for most SaaS applications.
• Scale — Media-heavy applications, CDN origins, or services with significant egress.
• Enterprise — Large-scale production workloads, data lakes, or high-throughput APIs.

If you're unsure, start with Starter or Growth and upgrade later. Upgrades are instant and prorated to your billing cycle, and going a little over the allowance in the meantime is billed as overage rather than stopping the bucket.

Usage Monitoring

Cosmoner tracks storage, egress, and request usage per bucket once a day and compares it against the bucket's allowances.

Warning Threshold (80%)

When any dimension reaches 80% of its allowance, you receive an in-app notification and email alert, once per billing period. No action is taken on the bucket — this is an early warning to consider upgrading.

Usage Above the Plan

A bucket that goes past an allowance keeps working. What it uses above the allowance is billed as overage: storage per GB-month, egress per GB, and requests per 10,000. The rates are on the Object Storage pricing page.

Overage Limit

To cap what a bucket can run up, set a monthly overage limit from the bucket's page, and choose what reaching it does:

• Alert emails the billing contact, once per billing period. The bucket keeps working.
• Block emails the billing contact and stops the bucket's files from being read or written — through access keys, public links and the CDN — until the next billing period starts. Listing and deleting files still work, and no data is deleted.

Raising or removing the limit, switching to Alert, or upgrading the tier unblocks a blocked bucket immediately. The same setting is available via the API:

PATCH /v1/projects/:projectId/storage/object-storage/:bucketId/overage-limit

{
  "overageLimitUsd": 50,
  "overageLimitAction": "BLOCK"
}

Send "overageLimitUsd": null to remove the limit.

Changing Plans

The bucket overview page lists every tier next to your current one. Selecting a tier opens a confirmation dialog showing how your allowances change and exactly what the change costs before anything is charged.

Tier changes are:

• Instant — the new tier's allowances apply immediately.
• Prorated — billing is adjusted for the remaining billing period.

The same change is available via the API:

PATCH /v1/projects/:projectId/storage/object-storage/:bucketId/tier

{
  "tier": "GROWTH"
}

Upgrading

The prorated difference for the rest of the current billing period is charged to your payment method immediately, and the new monthly price applies from your next invoice. If the bucket was blocked at its overage limit, upgrading unblocks it.

To see the amount before committing, call the preview endpoint:

GET /v1/projects/:projectId/storage/object-storage/:bucketId/plan-preview?tier=GROWTH

Downgrading

You can downgrade to a lower tier if your current usage fits within the target tier's limits. If any dimension (storage, egress, or requests) exceeds the lower tier's allowance, the downgrade is blocked — reduce usage or wait for the next billing cycle before retrying.

Downgrades charge nothing. The unused part of your current plan is credited to your account balance and applied to future invoices rather than refunded to your card.

Creating a Bucket

POST /v1/projects/:projectId/storage/object-storage

{
  "name": "my-bucket",
  "provider": "AWS_S3",
  "region": "eu-north-1",
  "tier": "STARTER"
}

Bucket names are globally unique, 3–33 characters, lowercase letters, numbers, and hyphens only.

If your project does not have an active subscription, the API returns a Stripe Checkout URL to complete payment. Once payment is confirmed, the bucket is provisioned automatically.

Regions

Buckets can be created in any of the following AWS regions:

Choose a region close to your application servers to minimize latency and egress costs.

Public Access & CDN

By default, buckets are private — objects can only be accessed with signed credentials. There are two ways to serve objects without them, and you can use either or both:

• Public access (publicAccess: true) serves objects over a public, unauthenticated HTTPS URL, shown as the Public URL on the bucket overview page.
• CDN (cdnEnabled: true) serves objects from edge locations worldwide for lower latency and faster delivery, shown as the CDN URL once provisioned. The CDN does not need public access: on a private bucket, the CDN URL is the only way to read objects without credentials.

Serving only some folders

Both serve the whole bucket unless you list folders in publicPaths. Then only objects under those folders are served — on the Public URL and the CDN alike — and everything else still needs credentials. This lets one bucket hold private files next to, say, the images your emails link to.

• A folder covers everything beneath it: images/ serves images/logo.png and images/2026/hero.jpg, but not images-old/.
• Folders use letters, digits, ., _, - and /. A leading / is dropped and a trailing one is added for you.
• Up to 10 folders. An empty list means the whole bucket.

Set them when creating the bucket, or change them later on the bucket overview page or with:

PATCH /v1/projects/:projectId/storage/object-storage/:bucketId/access

{
  "publicAccess": false,
  "publicPaths": ["email/", "images/"]
}

Send both fields — together they replace the bucket's current settings.

CDN pricing

The CDN is an opt-in add-on:

• Delivery is metered at USD 0.12/GB and USD 0.015 per 10K requests, billed as extra line items on the bucket's subscription.
• It can be toggled on or off at any time, either from the bucket overview page or via the API:

PATCH /v1/projects/:projectId/storage/object-storage/:bucketId/cdn

{
  "cdnEnabled": true
}

Disabling the CDN removes the added cost. The bucket stays reachable on its Public URL if publicAccess is on, and becomes fully private if it is not.

CORS

If your bucket is accessed directly from a browser (for example, uploading files from a web app or serving public assets to a single-page application), you need Cross-Origin Resource Sharing (CORS) rules so the browser allows those cross-origin requests.

You can define CORS rules when creating a bucket, and edit them at any time from the bucket's settings. Each rule specifies:

• Allowed origins — the web origins permitted to make requests (e.g. https://example.com), or * for any origin.
• Allowed methods — one or more of GET, PUT, POST, DELETE, HEAD.
• Allowed headers (optional) — request headers the browser may send (use * to allow all).
• Expose headers (optional) — response headers the browser is allowed to read (e.g. ETag).
• Max age (optional) — how long, in seconds, the browser may cache the preflight response.

To update CORS on an existing bucket:

PATCH /v1/projects/:projectId/storage/object-storage/:bucketId/cors

{
  "corsRules": [
    {
      "allowedOrigins": ["https://example.com"],
      "allowedMethods": ["GET", "PUT"],
      "allowedHeaders": ["*"],
      "maxAgeSeconds": 3600
    }
  ]
}

The request replaces the entire CORS configuration — send the complete rule set each time. An empty array removes all CORS rules.

Deleting a Bucket

DELETE /v1/projects/:projectId/storage/object-storage/:bucketId

Deleting a bucket is irreversible. All objects stored in it are permanently removed and the associated subscription item is cancelled.