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

# Get Blob Storage usage

> Read your Blob Storage usage with GET /v1/account/stats: files, bytes, included storage, this month's average and the estimate of any storage beyond the quota.

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

Account Stats returns a snapshot of your Blob Storage usage: number of files, bytes stored, the storage included in your plan, this month's average usage and the estimated cost of anything held beyond the included storage (R\$ 0.20 per started GiB). Use it to build a usage meter or check headroom before a large batch of uploads. Requires the `blob:read` scope.

The response is cached for 1 minute, and your own uploads and deletes clear that cache, so they show up right away.

## Rate limits

<Note>20 requests per minute, 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="usage" type="object">
      <ResponseField name="objects" type="number">
        The number of files in your account.
      </ResponseField>

      <ResponseField name="storage" type="number">
        The total size of your files, in bytes.
      </ResponseField>
    </ResponseField>

    <ResponseField name="plan" type="object">
      <ResponseField name="included" type="number">
        The storage included in your plan, in bytes.
      </ResponseField>
    </ResponseField>

    <ResponseField name="billing" type="object">
      <ResponseField name="extraStorage" type="number">
        The storage beyond the included amount, in bytes.
      </ResponseField>

      <ResponseField name="storagePrice" type="number">
        The estimated cost of that storage, in BRL (R\$ 0.20 per started GiB).
      </ResponseField>

      <ResponseField name="objectsPrice" type="number">
        Reserved for per-file pricing; always 0.
      </ResponseField>

      <ResponseField name="totalEstimate" type="number">
        The total estimate, in BRL.
      </ResponseField>
    </ResponseField>

    <ResponseField name="month" type="object">
      <ResponseField name="days" type="number">
        How many days of the current month (UTC) have a usage sample.
      </ResponseField>

      <ResponseField name="average_storage" type="number">
        The average of those daily samples, in bytes.
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/account/stats' \
    --header 'Authorization: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json Response - [1m cache] theme={"system"}
  {
    "status": "success",
    "response": {
      "usage": {
        "objects": 1284,
        "storage": 3221225472
      },
      "plan": {
        "included": 5368709120
      },
      "billing": {
        "extraStorage": 0,
        "storagePrice": 0,
        "objectsPrice": 0,
        "totalEstimate": 0
      },
      "month": {
        "days": 24,
        "average_storage": 3006477107
      }
    }
  }
  ```
</ResponseExample>

## Errors

| Code | HTTP | When |
| - | - | - |
| `RATE_LIMITED` | 429 | More than 20 requests in a minute. |

## Related

* Blob SDK: [`blob.stats()`](/en/sdks/blob/rules_and_stats)


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