List files in Blob Storage

GET

objects

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

let cursor;
do {
  const params = new URLSearchParams({ prefix: 'images/', limit: '1000' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  for (const object of response.objects) console.log(object.id, object.size);
  cursor = response.continuationToken;
} while (cursor);

import requests

cursor = None
while True:
    params = {'prefix': 'images/', 'limit': 1000}
    if cursor:
        params['cursor'] = cursor
    response = requests.get(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params=params,
    ).json()['response']
    for obj in response['objects']:
        print(obj['id'], obj['size'])
    cursor = response.get('continuationToken')
    if not cursor:
        break

{
  "status": "success",
  "response": {
    "objects": [
      {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
      },
      {
        "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "size": 90466,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": true,
        "url": null,
        "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\""
      }
    ],
    "folders": ["images/icons/"],
    "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c"
  }
}

string

required

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

Object List enumerates the files stored under your account, optionally filtered by prefix and visibility, and paginates with a cursor instead of returning everything at once. Use it to build a file browser, confirm an upload landed, or reconcile your own records against what Blob Storage holds. Requires the blob:read scope. Pages are cached for 30 minutes per set of parameters, and your own uploads and deletes clear that cache, so they show up right away. The order of the results is not guaranteed. A page can hold fewer than limit objects while more remain: keep requesting until continuationToken is absent.

Parameters

string

Only files whose path starts with this string (for example images/ or images/2026-). Letters, digits, _, ., - and /, up to 256 characters.

string

Only /. Groups the files below the next / into folders instead of listing them, like a directory listing.

boolean

true lists only private files, false only public ones. Omit it to list both.

number

default:"1000"

Maximum number of entries per page, from 1 to 1000.

string

The continuationToken of the previous page. continuationToken is also accepted as the parameter name.

Rate limits

30 requests per 30 seconds, blocked for a short period past that (RATE_LIMITED, 429).

Response

string

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

object

Show Toggle object

array

Show Toggle object

string

The object id. Treat it as opaque.

integer

The size of the file, in bytes.

ISO 8601

When the file was stored.

ISO 8601

When the file will be deleted. Omitted for files that don’t expire.

boolean

Whether the file is private.

string | null

The public URL, or null for private files.

string

The ETag of the file. It changes when the content changes.

string[]

The folders below prefix, each ending in /. Present only with delimiter=/.

string

Send it back as cursor to get the next page. Absent on the last page.

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

let cursor;
do {
  const params = new URLSearchParams({ prefix: 'images/', limit: '1000' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  for (const object of response.objects) console.log(object.id, object.size);
  cursor = response.continuationToken;
} while (cursor);

import requests

cursor = None
while True:
    params = {'prefix': 'images/', 'limit': 1000}
    if cursor:
        params['cursor'] = cursor
    response = requests.get(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params=params,
    ).json()['response']
    for obj in response['objects']:
        print(obj['id'], obj['size'])
    cursor = response.get('continuationToken')
    if not cursor:
        break

{
  "status": "success",
  "response": {
    "objects": [
      {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
      },
      {
        "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "size": 90466,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": true,
        "url": null,
        "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\""
      }
    ],
    "folders": ["images/icons/"],
    "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c"
  }
}

Errors

Code	HTTP	When
`INVALID_OBJECT_PREFIX`	400	`prefix` has characters outside the pattern or contains `..`.
`INVALID_DELIMITER`	400	`delimiter` is not `/`.
`INVALID_OBJECT_PRIVATE`	400	`private` is not `true` or `false`.
`INVALID_LIMIT`	400	`limit` is not an integer from 1 to 1000.
`INVALID_CONTINUATION_TOKEN`	400	The `cursor` (or `continuationToken`) is malformed or no longer valid. Start again without a cursor.
`RATE_LIMITED`	429	More than 30 requests in 30 seconds.

Blob SDK: blob.list(), blob.listPage()

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

let cursor;
do {
  const params = new URLSearchParams({ prefix: 'images/', limit: '1000' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  for (const object of response.objects) console.log(object.id, object.size);
  cursor = response.continuationToken;
} while (cursor);

import requests

cursor = None
while True:
    params = {'prefix': 'images/', 'limit': 1000}
    if cursor:
        params['cursor'] = cursor
    response = requests.get(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params=params,
    ).json()['response']
    for obj in response['objects']:
        print(obj['id'], obj['size'])
    cursor = response.get('continuationToken')
    if not cursor:
        break

{
  "status": "success",
  "response": {
    "objects": [
      {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
      },
      {
        "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "size": 90466,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": true,
        "url": null,
        "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\""
      }
    ],
    "folders": ["images/icons/"],
    "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c"
  }
}

Get started

Objects

Chunked uploads

Account

Share links

S3

List files in Blob Storage

Parameters

Rate limits

Response

Errors

​Parameters

​Rate limits

​Response

​Errors

​Related

Parameters

Rate limits

Response

Errors

Related