> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob 分块上传状态

> 通过 GET /v1/objects/chunked 查看分块上传中哪些分块已经送达，以便恢复中断的上传。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

分块状态会列出一个未完成上传中已经存储的分块。在崩溃、连接中断或页面刷新之后，可用它来**恢复**上传：只通过[分块发送](/zh/blob-reference/endpoint/chunked-part)发送缺失的分块，然后调用[分块完成](/zh/blob-reference/endpoint/chunked-complete)。需要 `blob:write` scope。

如果你连 `upload` 令牌也弄丢了，[未完成上传](/zh/blob-reference/endpoint/chunked-open)会列出账户所有未完成的上传及其令牌。

<ParamField query="upload" type="string" required>
  分块初始化返回的 `upload` 令牌。
</ParamField>

### 速率限制

<Note>每 10 秒 10 次请求（`RATE_LIMITED`，429）。用它来恢复上传，而不是轮询进度：你的客户端已经知道它发送了哪些分段。</Note>

### 响应

<ResponseField name="status" type="string">
  成功为 "success"，否则为 "error"。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="id" type="string">
      文件完成后将拥有的 id。
    </ResponseField>

    <ResponseField name="parts" type="array">
      已存储的分块，每个以 `{ "part", "size", "etag" }` 表示。
    </ResponseField>

    <ResponseField name="next_part" type="number">
      尚未存储的最小分块编号。
    </ResponseField>

    <ResponseField name="size_so_far" type="number">
      到目前为止已存储的总字节数。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN' \
    --header 'Authorization: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
      "parts": [
        { "part": 1, "size": 16777216, "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\"" },
        { "part": 2, "size": 16777216, "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\"" },
        { "part": 4, "size": 16777216, "etag": "\"e1f0a9b8c4a2f0b1c9d8e7f6a5b4c3d2\"" }
      ],
      "next_part": 3,
      "size_so_far": 50331648
    }
  }
  ```
</ResponseExample>

### 错误

| 代码                     | HTTP | 触发情况                     |
| ---------------------- | ---- | ------------------------ |
| `INVALID_UPLOAD_TOKEN` | 400  | `upload` 令牌缺失、格式错误或不属于你。 |
| `UPLOAD_NOT_FOUND`     | 404  | 该上传已完成、已中止或已过期。          |
| `RATE_LIMITED`         | 429  | 10 秒内超过 10 次请求。          |