Migrate objects from another provider

A migration copies the objects of a bucket at another provider into one of your buckets. We read from the other provider with an access key you give us, copy each object with its content headers and metadata, and keep going in the background until every object is copied. Nothing changes at the other provider. Copies are free; the objects they create are billed as storage.

• Sign in to the dashboard and open the Object Storage service. The service must be active.
• Create the bucket to copy into (Create and delete buckets). It can already hold objects.
• At the other provider, create an access key that can list and read the bucket. Source details by provider says where each provider keeps it. A key that can only read is enough, and is the safest choice.

Each provider needs a bucket name and an access key. Some also need a region or an endpoint, which the dialog asks for when you choose the provider.

An endpoint you type must use HTTPS and be on the public internet. We refuse one that points at a private or reserved address, and one that is Coritan Object Storage itself: to copy between your own buckets, use replication or an S3 client.

1. In the dashboard, go to Object Storage, open the service, then the Migrations tab.
2. Select New migration….
3. Under Copy from, choose the Provider. Fill in the Endpoint or Region when the dialog asks for one (Source details by provider).
4. Enter the source Bucket name. 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.
5. Enter the Access key ID and Secret access key.
6. Under Copy to, choose the Bucket to copy into. To put the copies under a folder, enter a Prefix, such as imported/: photos/beach.jpg becomes imported/photos/beach.jpg. Leave it empty to keep the keys as they are.
7. Leave Copy every object again off to skip an object your bucket already holds with the same key, size and ETag. Turn it on to copy every object whatever your bucket holds.
8. Optionally, select Check source. We list the source with the key and show the first keys we found, so you know the details are right. Nothing is copied yet.
9. Select Start migration. We check the source again before we start.

The migration appears at the top of the list as Queued and starts within a minute. It runs in the background, so you can close the dashboard. The list refreshes itself while a migration is queued or copying.

Progress also shows how much data was copied, how many objects were already in your bucket and skipped, and how many failed.

When a migration ends, in any of the last four states, we delete the access key you gave us.

• Each object's current version, under the destination prefix followed by its source key.
• Its Content-Type, Cache-Control, Content-Disposition, Content-Encoding and Content-Language headers, and its user metadata (x-amz-meta-*).
• Its ETag, in most cases. An object the source uploaded in parts is copied in parts of the same size, so S3 clients that compare ETags see the same value at both ends.

These are not copied: earlier versions of an object, object tags, access control lists, storage classes, retention and legal holds, and the bucket's own settings (CORS, lifecycle, public access, notifications). Set those on your bucket yourself.

An object that changes at the source while we copy it fails with "The object changed while we copied it". Retry the migration to copy its new version.

It depends mostly on how fast the source sends data, and on how many objects there are: a bucket of many small objects takes longer than one of a few large objects with the same total size. We copy several small objects at once, and an object larger than 16 MB in parts. The Migrations tab shows how far each migration has got.

A service runs at most 3 migrations at a time. To copy several buckets, start one migration for each; the fourth waits until one ends.

An object that cannot be copied does not stop the migration: we record it as failed and move on. When the source is busy or does not answer, we stop for now and carry on from the same place a minute later. The reasons an object fails:

• "The source refused to send it (AccessDenied)": the key cannot read that object. Change its permissions at the source.
• "The source keeps it in an archive class that must be restored first": the object is in an archive class, such as S3 Glacier. Restore it at the source.
• "The object changed while we copied it", or "The source no longer has it".
• "Objects over 625 GB are not copied. Copy it with an S3 client".
• "The key is longer than 1024 bytes with the destination prefix": choose a shorter destination prefix.

To see them, open the migration's menu (…) and select Show failed objects. Failed objects lists the most recent first, with the reason and how many times we tried. We keep the last 1000 failures of each migration.

To try again after fixing the cause:

1. Select Retry failed objects…, in the migration's menu or on the Failed objects card.
2. Enter the Access key ID and Secret access key again. We deleted them when the migration ended. The dialog shows the last four characters of the key the migration used.
3. Select Retry failed objects.

The migration is queued again. It copies the failed objects first, then anything it had not reached. When more objects failed than the 1000 we keep, it walks the whole source again and skips what your bucket already holds.

A migration that Failed has Retry migration… instead. It carries on from where it stopped.

A migration stops with Failed when the source refuses the key or the bucket, when the destination bucket is deleted, when the first 100 objects all fail, or when the source has not answered 10 times in a row.

1. Open the migration's menu (…) and select Cancel migration….
2. Select Cancel migration to confirm, or Keep copying to leave it running.

We stop copying and delete the access key. The objects already copied stay in your bucket, and nothing changes at the source. A cancelled migration cannot be started again: start a new one, and leave Copy every object again off so it skips what is already copied.

Migrations are free: the requests we make to your bucket are not counted as operations. The objects they create count as storage in your service, like any object you upload (How Object Storage is billed). Your old provider may charge for the data and the requests we read from it; check its pricing.

Every request takes your access token as Authorization: Bearer $CORITAN_TOKEN. Find the service's id and the bucket's id with GET /api/v1/client/object-storage and GET /api/v1/client/object-storage/{service_id}/buckets.

Check the source. It answers 422 with the reason when the source refuses, and stores nothing:

curl -X POST https://api.coritan.com/api/v1/client/object-storage/106/migrations/preflight \
  -H "Authorization: Bearer $CORITAN_TOKEN" -H "Content-Type: application/json" \
  -d '{"provider": "aws", "region": "us-east-1", "source_bucket": "example-media",
       "source_prefix": "", "access_key_id": "AKIAEXAMPLE", "secret_access_key": "..."}'

{
  "ok": true,
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "region": "us-east-1",
  "bucket": "example-media",
  "prefix": "",
  "sample": [{ "key": "index.html", "size": 18204, "last_modified": "2026-09-08T19:41:15+00:00" }],
  "more": true
}

provider is one of aws, r2, gcs, b2, wasabi, digitalocean and other. endpoint is required for r2 and other; region for aws, b2, wasabi and digitalocean.

Start the migration with the same fields, plus bucket_id, dest_prefix and overwrite (Copy every object again). It answers 201 with the migration:

curl -X POST https://api.coritan.com/api/v1/client/object-storage/106/migrations \
  -H "Authorization: Bearer $CORITAN_TOKEN" -H "Content-Type: application/json" \
  -d '{"provider": "aws", "region": "us-east-1", "source_bucket": "example-media",
       "access_key_id": "AKIAEXAMPLE", "secret_access_key": "...",
       "bucket_id": 501, "dest_prefix": "", "overwrite": false}'

{
  "id": 42,
  "bucket_id": 501,
  "bucket_name": "u7-assets",
  "provider": "aws",
  "provider_label": "Amazon S3",
  "source_bucket": "example-media",
  "status": "queued",
  "listed_all": false,
  "objects_listed": 0,
  "objects_copied": 0,
  "objects_skipped": 0,
  "objects_failed": 0,
  "bytes_copied": 0,
  "can_retry": false,
  "error": null
}

GET .../migrations lists the service's migrations, newest first, with the provider presets and limits. GET .../migrations/{migration_id} answers one. objects_listed is the total only once listed_all is true.

POST .../migrations/{migration_id}/cancel cancels a queued or running migration. POST .../migrations/{migration_id}/retry, with access_key_id and secret_access_key, queues one whose can_retry is true again. GET .../migrations/{migration_id}/failures?limit=100&offset=0 lists its failed objects:

{
  "items": [{ "key": "db/2026-01-10/dump-000.sql.gz", "size": 116391936, "error": "The object changed while we copied it",
              "attempts": 2, "retry_pending": false, "updated_at": "2026-10-06T18:41:15+00:00" }],
  "total": 19,
  "kept_max": 1000
}

The API answers 404 for a service, bucket or migration that is not yours, 409 when the service is not active or already runs 3 migrations, and 429 past the rate limits above.

"The source did not accept the access key ID" or "The source did not accept the secret access key"

Copy the key again from the provider. A key with a session token does not work; create a long-lived access key.

"The key cannot list bucket. Give it permission to list and read the bucket"

The key exists but has no permission on that bucket. Add list and read permission at the provider.

"The source has no bucket named bucket"

Check the bucket name, and for providers with regions, the region.

"bucket is in another region. Choose the bucket's region and try again"

Choose the region the provider shows for the bucket.

"We could not find host. Check the endpoint and the region"

The endpoint's host name does not exist. Check for a typo, and that the region is a real one for the provider.

"host points at a private or reserved address. Migrations copy only from public endpoints"

Use the service's public HTTPS address.

"This service already has 3 migrations in progress. Wait for one to finish or cancel one"

Wait for a migration to end, or cancel one, then start the next.

• Replicate a bucket to another region
• Connect an S3 client
• How Object Storage is billed