> ## 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.

# List files in Blob Storage

> List the files in your Blob Storage with GET /v1/objects: filter by prefix and visibility, browse folders and paginate with a cursor.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

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

<ParamField query="prefix" type="string" placeholder="images/">
  Only files whose path starts with this string (for example `images/` or `images/2026-`). Letters, digits, `_`, `.`, `-` and `/`, up to 256 characters.
</ParamField>

<ParamField query="delimiter" type="string" placeholder="/">
  Only `/`. Groups the files below the next `/` into `folders` instead of listing them, like a directory listing.
</ParamField>

<ParamField query="private" type="boolean">
  `true` lists only private files, `false` only public ones. Omit it to list both.
</ParamField>

<ParamField query="limit" type="number" default="1000">
  Maximum number of entries per page, from 1 to 1000.
</ParamField>

<ParamField query="cursor" type="string">
  The `continuationToken` of the previous page. `continuationToken` is also accepted as the parameter name.
</ParamField>

## Rate limits

<Note>30 requests per 30 seconds, blocked for a short period past that (`RATE_LIMITED`, 429).</Note>

## Response

<ResponseField name="status" type="string">
  "success" if successful, "error" if not.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Toggle object">
    <ResponseField name="objects" type="array">
      <Expandable title="Toggle object">
        <ResponseField name="id" type="string">
          The object id. Treat it as opaque.
        </ResponseField>

        <ResponseField name="size" type="integer">
          The size of the file, in bytes.
        </ResponseField>

        <ResponseField name="created_at" type="ISO 8601">
          When the file was stored.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601">
          When the file will be deleted. Omitted for files that don't expire.
        </ResponseField>

        <ResponseField name="private" type="boolean">
          Whether the file is private.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          The public URL, or `null` for private files.
        </ResponseField>

        <ResponseField name="etag" type="string">
          The ETag of the file. It changes when the content changes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="folders" type="string[]">
      The folders below `prefix`, each ending in `/`. Present only with `delimiter=/`.
    </ResponseField>

    <ResponseField name="continuationToken" type="string">
      Send it back as `cursor` to get the next page. Absent on the last page.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={"system"}
  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);
  ```

  ```python Python theme={"system"}
  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
  ```
</RequestExample>

<ResponseExample>
  ```json Response - [30m cache] theme={"system"}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## 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. |

## Related

* Blob SDK: [`blob.list()`](/en/sdks/blob/objects), [`blob.listPage()`](/en/sdks/blob/objects)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.