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

# Blob Object List

> This documentation provides a comprehensive overview of the GET /v1/objects endpoint of the SquareCloud Blob API.

<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 scoped to a name prefix, and paginates through large buckets with a continuation token instead of returning everything at once. Use it to build a file browser, confirm an upload landed, or reconcile your own records against what Square Cloud actually holds.

Each page is cached per account, prefix, and token for 30 minutes, so repeated calls with the same parameters are served from cache rather than hitting storage again. Calls beyond 10 requests per 30 seconds are blocked for 30 seconds. Objects uploaded with an expiration carry an `expires_at` field; permanent objects omit it.

To remove an object once you've found its ID, see [Object Delete](/en/blob-reference/endpoint/delete); to upload new files, see [Object Post](/en/blob-reference/endpoint/post).

<ParamField query="prefix" type="string" placeholder="File Prefix">
  A string representing the prefix for the file.<br />Must adhere to the a to z, A to Z, 0 to 9, and \_ pattern. (3 to 32 characters)
</ParamField>

<ParamField query="continuationToken" type="string" placeholder="Continuation Token">
  A string representing the continuation token for the file list. (1000 objects per page)
</ParamField>

### Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful. "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 id of the object.
        </ResponseField>

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

        <ResponseField name="created_at" type="ISO 8601">
          The date and time the object was created.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601">
          The date and time the object will expire.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="continuationToken" type="string">
      Token to fetch the next page; pass it back as the `continuationToken` query parameter. `null` or absent when there are no more objects.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response - [30m cache] theme={null}
  {
    "status": "success",
    "response": {
      "objects": [
        {
          "id": "ID/name1_ltq7b2sw-de6241.jpeg",
          "size": 78266,
          "created_at": "2024-03-13T19:31:28.776Z"
        },
        {
          "id": "ID/name_ltq7b2sw-de6243-ex1.jpeg",
          "size": 90466,
          "created_at": "2024-03-13T19:35:28.776Z",
          "expires_at": "2024-03-14T19:35:28.776Z"
        }
      ],
      "continuationToken": null
    }
  }
  ```
</ResponseExample>

### Troubleshooting

<Tabs>
  <Tab title="400 Status Code">
    ### Object-Related

    <CodeGroup>
      ```json INVALID_OBJECT_PREFIX theme={null}
      // The provided object prefix is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_PREFIX"
      }
      ```

      ```json INVALID_CONTINUATION_TOKEN theme={null}
      // The provided continuation token is invalid (must be a string up to 2048 characters).
      {
          "status": "error",
          "code": "INVALID_CONTINUATION_TOKEN"
      }
      ```

      ```json LIST_FAILED theme={null}
      // The request to list the objects failed. Please try again.
      {
          "status": "error",
          "code": "LIST_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="401 Status Code">
    ### Unauthorized

    <CodeGroup>
      ```json ACCESS_DENIED theme={null}
      // The API key is missing or invalid. Set a valid key in the Authorization header.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="429 Status Code">
    ### Rate limited

    <CodeGroup>
      ```json RATE_LIMITED theme={null}
      // List rate limit reached (10 requests per 30s window, blocked for 30s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>