> ## 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/shares 列出你账户中有效的分享链接，包括过期时间、剩余下载次数和密码状态。

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

分享列表会返回账户中所有未过期且未被撤销的分享链接，以及每个链接剩余的下载次数。需要 `blob:read` scope。如果某个链接对应的文件已被删除、移动或更改了可见性，该链接会在首次被打开时从列表中移除。

### 速率限制

<Note>每分钟 20 次请求（`RATE_LIMITED`，429）。</Note>

### 响应

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

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="shares" type="array">
      <Expandable title="展开对象">
        <ResponseField name="id" type="string">
          分享 id。
        </ResponseField>

        <ResponseField name="url" type="string">
          链接。
        </ResponseField>

        <ResponseField name="object" type="string">
          被分享文件的 id。
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601">
          链接的过期时间。
        </ResponseField>

        <ResponseField name="remaining_downloads" type="number | null">
          剩余下载次数，没有上限时为 `null`。
        </ResponseField>

        <ResponseField name="password" type="boolean">
          链接是否要求输入密码。
        </ResponseField>

        <ResponseField name="created_at" type="ISO 8601">
          链接的创建时间。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "shares": [
        {
          "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
          "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
          "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
          "expires_at": "2026-10-02T12:00:00.000Z",
          "remaining_downloads": 3,
          "password": false,
          "created_at": "2026-09-25T12:00:00.000Z"
        }
      ]
    }
  }
  ```
</ResponseExample>

### 错误

| 代码             | HTTP | 触发情况           |
| -------------- | ---- | -------------- |
| `RATE_LIMITED` | 429  | 一分钟内超过 20 次请求。 |