> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar objetos de blob em uma pasta

> Lista os objetos de blob da conta por prefixo de caminho, com as pastas e um cursor para a próxima página. Retorna até 1.000 objetos por chamada.

Lista os objetos de blob da conta na ordem dos caminhos. Use `prefix` para listar uma pasta e `delimiter=/` para receber as suas subpastas em `folders`. Envie o `cursor` retornado de volta para obter a próxima página; `cursor` é `null` na última página.

**Escopo:** `blob:read`.

**prefix** `string`

Somente objetos cujo `path` começa com este texto, por exemplo `images/`.

**delimiter** `string`

Agrupa os caminhos em pastas neste caractere, geralmente `/`. As pastas voltam em `folders` e não como objetos.

**visibility** `string`

Somente objetos `public` ou somente objetos `private`.

**cursor** `string`

O `cursor` da página anterior. Omita-o na primeira página.

**limit** `number`

Objetos por página, de 1 a 1000. Padrão `100`.

**workspace\_id** `string`

O ID do workspace, quando o blob pertence a um workspace. A chamada atua sobre o blob do proprietário do workspace e exige a permissão `blob:read` do workspace (`blob:manage` nas rotas que alteram dados). Deixe de fora para atuar sobre o seu próprio blob.

### Exemplo de requisição

```bash theme={null}
curl "https://blob.vertracloud.app/v1/objects?prefix=images/&delimiter=/&limit=100" \
  -H "Authorization: Bearer $VERTRA_API_KEY"
```

### Resposta

**response** `object`

A página de objetos, as suas subpastas e o cursor da próxima página.

**propriedades**

**objects** `object[]`

Objetos desta página. Cada item tem os campos de [Obter um objeto de blob](https://docs.vertracloud.app/pt-br/api-reference/endpoint/blob/objects/get.md).

**objects\[].id** `string`

ID estável do objeto.

**objects\[].path** `string`

Caminho completo dentro da conta.

**objects\[].size** `number`

Tamanho em bytes.

**objects\[].visibility** `string`

`public` ou `private`.

**objects\[].url** `string | null`

URL pública, ou `null` enquanto privado.

**folders** `string[]`

Prefixos de pasta terminando em `/`. Vazio sem um `delimiter`.

**cursor** `string | null`

Envie-o de volta como `cursor` para obter a próxima página. `null` na última página.

```json Response theme={null}
{
  "response": {
    "objects": [
      {
        "id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
        "path": "images/logo.png",
        "size": 48213,
        "content_type": "image/png",
        "etag": "9b2cf535f27731c974343645a3085d39",
        "sha256": null,
        "visibility": "public",
        "url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
        "cache_control": null,
        "content_disposition": "inline",
        "filename": null,
        "metadata": {},
        "expires_at": null,
        "created_at": "2026-10-14T12:00:00.000Z",
        "updated_at": "2026-10-14T12:00:00.000Z"
      }
    ],
    "folders": [
      "images/avatars/"
    ],
    "cursor": null
  }
}
```

### Respostas de erro

**code** `string`

O código de erro que indica o motivo da falha. Valores possíveis:

* `AUTH_TOKEN_MISSING` (`401`): o cabeçalho `Authorization` não foi enviado.
* `API_KEY_INVALID` (`401`): a chave de API não existe, foi revogada ou o segredo não confere.
* `API_KEY_SCOPE_DENIED` (`403`): a chave não tem o escopo que esta rota exige (`blob:read` ou `blob:write`); `details.required` informa qual.
* `WORKSPACE_PERMISSION_DENIED` (`403`): somente com `workspace_id`: você não é membro, ou o seu papel não tem a permissão de blob.
* `WORKSPACE_NOT_FOUND` (`404`): somente com `workspace_id`: não existe workspace com esse ID, ou você não é membro.
* `VALIDATION_ERROR` (`400`): um parâmetro falhou na validação, com `details.path` indicando qual. Um `cursor` malformado, ou de outra consulta, retorna este erro com `details.path` igual a `cursor`.

```json Error Response (401) theme={null}
{
  "code": "AUTH_TOKEN_MISSING"
}
```

```json Error Response (403) theme={null}
{
  "code": "API_KEY_SCOPE_DENIED"
}
```

```json Error Response (404) theme={null}
{
  "code": "WORKSPACE_NOT_FOUND"
}
```

```json Error Response (400) theme={null}
{
  "code": "VALIDATION_ERROR"
}
```


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