# Replicate a bucket to another region

> Keep a copy of a bucket's objects in one of your buckets in another region, with new and changed objects copied every 5 minutes.

Source: https://www.coritan.com/docs/object-storage/replication/

In the dashboard:

- /dashboard/storage/…/buckets/…/replication: https://www.coritan.com/dashboard/storage

A *replication rule* keeps a copy of a bucket's objects in another of your buckets, in a different region. When you add a rule, we copy the objects already in the bucket once. After that we copy new and changed objects every 5 minutes, and compare the two buckets once a day. Use it to keep a second copy of your data far from the first, or to serve the same files from two regions. Replication is free; the copies are billed as storage.

## Before you begin

- Sign in to the [dashboard](https://www.coritan.com/dashboard/storage). The service that holds the bucket must be `active` to add or change a rule.
- Have a bucket in another region to copy into. It can belong to any of your Object Storage services, so if you have no service in another region, [order one](/docs/object-storage/order-object-storage/) and [create a bucket](/docs/object-storage/buckets/) in it first. Its service must be `active` too.
- Decide whether deletes should be copied ([Replicated deletes](#replicated-deletes)).

## Add a rule

1. In the dashboard, go to [**Object Storage**](https://www.coritan.com/dashboard/storage), open the service, then the **Buckets** tab. Open the bucket, then **Replication**.
2. Select **Add rule…**.
3. Choose the **Destination bucket**. The list holds your buckets in other regions; a bucket whose service is not active cannot be chosen.
4. To copy part of the bucket, enter a **Prefix**: only keys that start with it are copied, such as `photos/` for `photos/2026/beach.jpg`. Capitals count. Leave it empty to copy every key.
5. Turn on **Replicate deletes** if objects deleted here should be deleted from the destination too.
6. Select **Add rule**.

## Result

The rule appears in the list as **First copy**, and the first copy starts within 5 minutes. Each object keeps its key: `photos/beach.jpg` here is `photos/beach.jpg` in the destination. When the first copy has finished, the rule shows **Up to date**.

| Status | API word | Meaning |
| --- | --- | --- |
| **First copy** | `copying` | Copying the objects that were in the bucket when you added the rule, or when you changed its prefix. |
| **Up to date** | `active` | The last pass copied everything. |
| **Behind** | `error` | Some objects could not be copied on the last pass. The reason shows under the status, and the next pass tries them again. |
| **Paused** | `paused` | You paused the rule. Nothing is copied until you turn it on. |

The **Copied** column shows the time up to which every change has been copied (`replicated_through` in the API), and how many objects and how much data the rule has copied in all.

## How replication runs

- Every 5 minutes we look for objects that were added or changed since the last pass, and copy the ones the destination lacks or holds differently. A bucket with many objects takes longer, because each pass reads the whole listing.
- Once a day we compare the two buckets key by key. This copies anything a pass missed, and with **Replicate deletes** on, deletes what the bucket no longer has.
- After a pass with failures, the next pass compares the buckets in full, so the objects that failed are copied as soon as they can be.

The rule waits while either bucket's service is not active, and carries on when it is.

## What is copied {#what-is-copied}

- Each object's current version, under the same key.
- Its `Content-Type`, `Cache-Control`, `Content-Disposition`, `Content-Encoding` and `Content-Language` headers, and its user metadata (`x-amz-meta-*`).
- Its ETag: an object uploaded in parts is copied in parts of the same size.

These are not copied: earlier versions of an object, object tags, and the bucket's own settings (CORS, lifecycle, public access, notifications). An object you upload straight to the destination stays there, unless **Replicate deletes** removes it ([Replicated deletes](#replicated-deletes)).

## Replicated deletes {#replicated-deletes}

With **Replicate deletes** off, the destination keeps every copy, even after the object is deleted here. That makes the destination a safety net against a mistaken delete.

With it on, the daily comparison deletes from the destination each object under the rule's prefix that this bucket no longer holds. Before each delete we check that the object is really gone here.

> [!WARNING]
> With **Replicate deletes** on, the daily comparison also deletes objects under the prefix that were uploaded straight to the destination. Keep the destination's keys for this rule alone.

For the same reason, a rule that replicates deletes cannot share keys in the destination with another rule: we refuse a second rule into the same bucket with an overlapping prefix when either of the two replicates deletes.

## Pause, edit or delete a rule

Open the rule's menu (**…**):

- **Pause rule…** stops copying. Select **Pause rule** to confirm. When you **Turn on** the rule again, we copy everything that changed while it was paused.
- **Edit rule…** changes the **Prefix** and **Replicate deletes**. Select **Save changes**. A new prefix starts a first copy for it. To copy to another bucket, add a new rule.
- **Delete rule…** stops copying. Type the destination bucket's name and select **Delete rule**. The copies already in the destination stay; delete them yourself if you no longer need them.

> [!NOTE]
> Deleting either bucket deletes its rules.

## Rules we refuse

- A destination in the same region: "Choose a bucket in another region. Replication copies between regions".
- The bucket itself, or a bucket of a service that is not active.
- A second rule to the same bucket with the same prefix.
- A circle: a rule into a bucket that already replicates into this one, directly or through another bucket.
- A rule that would share destination keys with one that replicates deletes ([Replicated deletes](#replicated-deletes)).

## Billing

Replication is free: the requests we make to read and write your buckets are not counted as operations. The copies count as storage in the destination's service, like any object you upload ([How Object Storage is billed](/docs/object-storage/usage-and-billing/)).

## Limits

| Limit | Value |
| --- | --- |
| Rules per bucket | 10 |
| Prefix | 1024 bytes |
| Largest object copied | 625 GB |
| Rule changes by one account | 60 an hour |

## With the API

Every request takes your access token as `Authorization: Bearer $CORITAN_TOKEN`. `{service_id}` and `{bucket_id}` are the source's.

List a bucket's rules, the buckets it can replicate to and the limit:

```bash
curl https://api.coritan.com/api/v1/client/object-storage/106/buckets/501/replication \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "items": [{
    "id": 71, "dest_bucket_id": 511, "dest_bucket_name": "u7-archive", "dest_region": "iad",
    "dest_location_name": "Ashburn", "prefix": "photos/", "replicate_deletes": true, "enabled": true,
    "status": "active", "replicated_through": "2026-10-08T12:55:00Z", "lag_seconds": 300,
    "objects_copied": 8204, "bytes_copied": 24481313587, "objects_deleted": 41,
    "last_failures": 0, "last_error": null
  }],
  "destinations": [{ "bucket_id": 511, "name": "u7-archive", "service_id": 119, "region": "iad",
                     "location_name": "Ashburn", "service_status": "active" }],
  "limits": { "rules_max": 10 }
}
```

Add a rule. It answers 201 with the rule:

```bash
curl -X POST https://api.coritan.com/api/v1/client/object-storage/106/buckets/501/replication \
  -H "Authorization: Bearer $CORITAN_TOKEN" -H "Content-Type: application/json" \
  -d '{"dest_bucket_id": 511, "prefix": "photos/", "replicate_deletes": false}'
```

`PUT .../replication/{rule_id}` takes any of `prefix`, `replicate_deletes` and `enabled` (`false` pauses the rule) and answers the rule. `DELETE .../replication/{rule_id}` answers `{"deleted": true, "id": 71}`.

The API answers 404 for a service, bucket or rule that is not yours, 422 for a destination in the same region or the bucket itself, 409 for the other [rules we refuse](#rules-we-refuse) and when the service is not active, and 429 past the rate limit. You can delete a rule whatever the service's state.

## Troubleshooting

The rule shows **Behind**
: The reason shows under the status. The next pass tries the failed objects again. An object in an archive class, or larger than 625 GB, fails each time.

The **Destination bucket** list is empty
: You have no bucket in another region. Create one in a service in another region, ordering one if you need to.

"The destination's service is suspended. Choose a bucket of an active service"
: Choose a bucket of another service, or add the rule once the destination's service is active again.

## Next steps

- [Migrate objects from another provider](/docs/object-storage/migrate-to-object-storage/)
- [Get notified when objects change](/docs/object-storage/event-notifications/)
- [How Object Storage is billed](/docs/object-storage/usage-and-billing/)

## API

- `GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication`: The bucket's replication rules, the buckets a new rule may copy to, and the limits (https://www.coritan.com/docs/api/reference/client/object-storage/object-storage-buckets/#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id-replication)
- `POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication`: Add replication rule (https://www.coritan.com/docs/api/reference/client/object-storage/object-storage-buckets/#op-post-api-v1-client-object-storage-service-id-buckets-bucket-id-replication)
- `PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication/{rule_id}`: Change a rule's prefix, turn replicated deletes on or off, or pause and resume it (https://www.coritan.com/docs/api/reference/client/object-storage/object-storage-buckets/#op-put-api-v1-client-object-storage-service-id-buckets-bucket-id-replication-rule-i)
- `DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication/{rule_id}`: Remove a rule (https://www.coritan.com/docs/api/reference/client/object-storage/object-storage-buckets/#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id-replication-rul)