List share links

List the active share links of your account with GET /v1/shares, with the expiry, remaining downloads and password status of each link still valid.

GET /v1/shares

cURL

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY'

{
  "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"
      }
    ]
  }
}

Authorization · string · required

The API key for your account. You can find this in your account settings.

List Shares returns every share link of the account that hasn’t expired or been revoked, with how many downloads each has left. Requires the blob:read scope. A link whose file was deleted, moved or changed visibility leaves the list the first time someone opens it.

Rate limits

20 requests per minute (RATE_LIMITED, 429).

Response

status · string

“success” if successful, “error” if not.

response · object

Show Toggle object

shares · array

Show Toggle object

id · string

The share id.

url · string

The link.

object · string

The id of the shared file.

expires_at · ISO 8601

When the link expires.

remaining_downloads · number | null

Downloads left, or null when there is no cap.

password · boolean

Whether the link asks for a password.

created_at · ISO 8601

When the link was created.

cURL

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY'

{
  "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"
      }
    ]
  }
}

Errors

Code	HTTP	When
RATE_LIMITED	429	More than 20 requests in a minute.

Related

• Blob SDK: blob.shares.list()