Get Upload

GET {uploadUrl} or /v1/uploads/{id}

Updated Sep 25, 2026·2 min read

Shows where an upload stands: its status, the bytes still missing and, once it is finished, the file. Use it to resume after an interruption. GET the upload URL with no API key, or GET /v1/uploads/{id} with your API key. Only a GET on the upload URL finishes an upload whose pieces all arrived but whose last answer was lost. GET /v1/uploads/{id} only reports, and never shows the upload URL.

Path parameters

Parameter		Description
`uploadUrl` string	optional	For `GET {uploadUrl}`: the `uploadUrl` from Create Upload, used exactly as returned.
`id` string	optional	For `GET /v1/uploads/{id}`: the upload's `id`, which starts with `upl_`.

Header parameters

Parameter		Description
`Authorization` string	optional	Only for `GET /v1/uploads/{id}`: `Bearer API_Key`. Never send it to the upload URL.

Example request

# With the upload URL: no API key
curl "$UPLOAD_URL"

# With the upload's id and your API key
curl 'https://api.cloudfiles.io/v1/uploads/upl_66f3c1a2b4d5e6f708192a3b' \
  --header 'Authorization: Bearer API_Key'

Response body

200 OK. Here, the first of three pieces has arrived:

{
  "id": "upl_66f3c1a2b4d5e6f708192a3b",
  "status": "uploading",
  "library": "s3",
  "driveId": "workspace",
  "name": "Q3-report.pdf",
  "size": 120000000,
  "chunkSize": 52428800,
  "chunkCount": 3,
  "maxConcurrency": 4,
  "bytesReceived": 52428800,
  "nextExpectedRanges": [
    "52428800-119999999"
  ],
  "expiresAt": "2026-09-25T11:00:04.000Z"
}

Output fields

Parameter		Description
`status` string		`created`, `uploading`, `completing` (the file is being put together), `completed`, `aborted` or `expired`. The last two never finish: create a new upload.
`nextExpectedRanges` string[]		Byte ranges still missing, as `first-last`. Send the piece that starts at the first number.
`expiresAt` string		When the upload expires unless another piece starts first.
`file` object		Once `completed`: the file, as in Upload Chunk.

A finished, cancelled or expired upload can be read for about seven days, then answers 404.

Errors

Status	errorCode	What it means
404	`UPLOAD/NOT_FOUND`	No upload with this URL or id in your account.
403	`COMMON/FORBIDDEN`	`GET /v1/uploads/{id}`: the API key is missing or unknown.
503	`UPLOAD/STORAGE_UNAVAILABLE`	The storage was busy while the GET finished the upload. Try again after `Retry-After` seconds.

A GET that finishes the upload can also return the errors a last piece can. See Upload Errors.

Upload Chunk

Cancel Upload