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

# Listar arquivos do Blob Storage

> Liste os arquivos do seu Blob Storage com GET /v1/objects: filtre por prefixo e visibilidade, navegue por pastas e pagine com um cursor.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

A Lista de Objetos enumera os arquivos armazenados na sua conta, com filtro opcional por prefixo e visibilidade, e pagina com um cursor em vez de retornar tudo de uma vez. Use-a para montar um navegador de arquivos, confirmar que um upload chegou ou conferir os seus próprios registros com o que o Blob Storage guarda. Exige o escopo `blob:read`.

As páginas ficam em cache por 30 minutos para cada conjunto de parâmetros, e os seus próprios uploads e exclusões limpam esse cache, então eles aparecem na hora. A ordem dos resultados não é garantida. Uma página pode trazer menos de `limit` objetos mesmo quando ainda há mais: continue fazendo requisições até `continuationToken` não aparecer.

## Parâmetros

<ParamField query="prefix" type="string" placeholder="images/">
  Apenas arquivos cujo caminho começa com esta string (por exemplo `images/` ou `images/2026-`). Letras, dígitos, `_`, `.`, `-` e `/`, até 256 caracteres.
</ParamField>

<ParamField query="delimiter" type="string" placeholder="/">
  Apenas `/`. Agrupa os arquivos abaixo da próxima `/` em `folders` em vez de listá-los, como em uma listagem de diretório.
</ParamField>

<ParamField query="private" type="boolean">
  `true` lista apenas arquivos privados, `false` apenas os públicos. Omita para listar ambos.
</ParamField>

<ParamField query="limit" type="number" default="1000">
  Número máximo de entradas por página, de 1 a 1000.
</ParamField>

<ParamField query="cursor" type="string">
  O `continuationToken` da página anterior. `continuationToken` também é aceito como nome do parâmetro.
</ParamField>

## Limites de taxa

<Note>30 requisições a cada 30 segundos, com bloqueio por um curto período acima disso (`RATE_LIMITED`, 429).</Note>

## Resposta

<ResponseField name="status" type="string">
  "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="objects" type="array">
      <Expandable title="Alternar objeto">
        <ResponseField name="id" type="string">
          O id do objeto. Trate-o como opaco.
        </ResponseField>

        <ResponseField name="size" type="integer">
          O tamanho do arquivo, em bytes.
        </ResponseField>

        <ResponseField name="created_at" type="ISO 8601">
          Quando o arquivo foi armazenado.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601">
          Quando o arquivo será excluído. Omitido para arquivos que não expiram.
        </ResponseField>

        <ResponseField name="private" type="boolean">
          Se o arquivo é privado.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          A URL pública, ou `null` para arquivos privados.
        </ResponseField>

        <ResponseField name="etag" type="string">
          O ETag do arquivo. Ele muda quando o conteúdo muda.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="folders" type="string[]">
      As pastas abaixo de `prefix`, cada uma terminando em `/`. Presente apenas com `delimiter=/`.
    </ResponseField>

    <ResponseField name="continuationToken" type="string">
      Envie-o de volta como `cursor` para obter a próxima página. Ausente na última página.
    </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 Resposta - [cache de 30m] 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>

## Erros

| Código | HTTP | Quando |
| - | - | - |
| `INVALID_OBJECT_PREFIX` | 400 | `prefix` tem caracteres fora do padrão ou contém `..`. |
| `INVALID_DELIMITER` | 400 | `delimiter` não é `/`. |
| `INVALID_OBJECT_PRIVATE` | 400 | `private` não é `true` nem `false`. |
| `INVALID_LIMIT` | 400 | `limit` não é um inteiro de 1 a 1000. |
| `INVALID_CONTINUATION_TOKEN` | 400 | O `cursor` (ou `continuationToken`) está malformado ou não é mais válido. Comece de novo sem cursor. |
| `RATE_LIMITED` | 429 | Mais de 30 requisições em 30 segundos. |

## Relacionados

* SDK do Blob: [`blob.list()`](/pt-br/sdks/blob/objects), [`blob.listPage()`](/pt-br/sdks/blob/objects)


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