> ## 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 Account Stats

> This documentation provides a comprehensive overview of the GET /v1/account/stats 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>

Account Stats returns a snapshot of your Blob Storage usage: object count, total bytes stored, how much of your plan's included storage you've used, and the estimated cost of anything over that allowance (R\$ 0.20 per started GiB). Use it to build a usage meter or check headroom before a large batch of uploads.

The response is cached per account for 1 minute, but a successful upload or delete invalidates that cache immediately, so your own writes show up right away even though the TTL bounds staleness from other sources. Calls are rate limited to 20 requests per 60 seconds, blocked for 60 seconds past that.

To see which objects make up your usage, check [Object List](/en/blob-reference/endpoint/list); to free up space, use [Object Delete](/en/blob-reference/endpoint/delete).

<Warning>Status updates every 1 minute.</Warning>

### 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="usage" type="object">
      <ResponseField name="objects" type="number">
        The total number of objects in your account.
      </ResponseField>

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

    <ResponseField name="plan" type="object">
      <ResponseField name="included" type="number">
        The total storage size included on the plan, in bytes.
      </ResponseField>
    </ResponseField>

    <ResponseField name="billing" type="object">
      <ResponseField name="extraStorage" type="number">
        The extra space used, in bytes.
      </ResponseField>

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

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

      <ResponseField name="totalEstimate" type="number">
        The total estimated overage cost for the account, in BRL.
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response - [1m cache] theme={null}
  {
    "status": "success",
    "response": {
      "usage": {
        "objects": 0,
        "storage": 0
      },
      "plan": {
        "included": 0
      },
      "billing": {
        "extraStorage": 0,
        "storagePrice": 0,
        "objectsPrice": 0,
        "totalEstimate": 0
      }
    }
  }
  ```
</ResponseExample>

### Troubleshooting

<Tabs>
  <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}
      // Stats rate limit reached (20 requests per 60s window, blocked for 60s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>