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

# Get Blob Storage Usage and Plan Limits

> Returns storage used, the plan's quota, the month average, image transformations used and the plan's limits.

Returns how much blob storage the account uses, its quota, the overage if any, and the `limits` of the current plan. Read the limits here instead of hardcoding them: they change with the plan. The values in the example are illustrative.

**Scope:** `blob:read`.

<ParamField query="workspace_id" type="string">
  The workspace ID, when the blob belongs to a workspace. The call acts on the blob of the workspace owner and needs the `blob:read` workspace permission (`blob:manage` on routes that change data). Leave it out to act on your own blob.
</ParamField>

### Example request

```bash theme={null}
curl "https://blob.vertracloud.app/v1/stats" \
  -H "Authorization: Bearer $VERTRA_API_KEY"
```

### Response

<ResponseField name="response" type="object">
  Usage, quota and the limits of the plan.

  <Expandable title="properties">
    <ResponseField name="objects" type="number">Number of objects stored.</ResponseField>
    <ResponseField name="used_bytes" type="number">Bytes stored now.</ResponseField>
    <ResponseField name="quota_bytes" type="number">Blob quota of the plan, in bytes.</ResponseField>
    <ResponseField name="over_quota_bytes" type="number">Bytes above the quota. Above 0 only after a plan downgrade.</ResponseField>
    <ResponseField name="estimated_overage_cents" type="number">Estimated charge for the bytes above the quota, in cents, billed at renewal: R\$0.20 per started GB.</ResponseField>
    <ResponseField name="month_average_bytes" type="number">Average stored bytes in the current month.</ResponseField>
    <ResponseField name="image_transformations_used" type="number">Image transformations used in the current month.</ResponseField>
    <ResponseField name="public_base_url" type="string">Base URL of the public files of the account.</ResponseField>
    <ResponseField name="limits.max_simple_upload_bytes" type="number">Largest file accepted by `POST /v1/objects`. 100 MB on every plan.</ResponseField>
    <ResponseField name="limits.max_single_put_bytes" type="number">Largest file that can be sent in one part of a direct upload.</ResponseField>
    <ResponseField name="limits.max_object_bytes" type="number">Largest single object, 10 GB.</ResponseField>
    <ResponseField name="limits.min_part_bytes" type="number">Smallest allowed part size for multipart uploads.</ResponseField>
    <ResponseField name="limits.max_part_bytes" type="number">Largest allowed part size for multipart uploads.</ResponseField>
    <ResponseField name="limits.max_parts" type="number">Most parts a multipart upload can have.</ResponseField>
    <ResponseField name="limits.max_open_uploads" type="number">How many direct uploads can be in progress at once on the plan.</ResponseField>
    <ResponseField name="limits.uploads_per_second" type="number | null">Uploads allowed per second. `null` means no limit of its own (Enterprise-12 or higher); below that, 1 per second.</ResponseField>
    <ResponseField name="limits.max_rules" type="number">Folder rules allowed: 5, 10 or 20, by plan.</ResponseField>
    <ResponseField name="limits.max_custom_domains" type="number">Custom domains allowed: 0, 1, 3 or 10, by plan.</ResponseField>
    <ResponseField name="limits.metadata_enabled" type="boolean">Whether `metadata` can be set (Enterprise-12 or higher).</ResponseField>
    <ResponseField name="limits.share_password_enabled" type="boolean">Whether share links can have a password (Enterprise-12 or higher).</ResponseField>
    <ResponseField name="limits.no_cache_enabled" type="boolean">Whether `cache_control: "no-cache"` is allowed (Enterprise-26 or higher).</ResponseField>
    <ResponseField name="limits.min_expiration_seconds" type="number">Shortest `expires_at` accepted, counted from now: 7 days, or 1 hour on Enterprise-26 or higher.</ResponseField>
    <ResponseField name="limits.image_transformations_per_month" type="number">Image transformations included per month. `0` on Economy and Pro.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "response": {
      "objects": 42,
      "used_bytes": 2147483648,
      "quota_bytes": 16106127360,
      "over_quota_bytes": 0,
      "estimated_overage_cents": 0,
      "month_average_bytes": 1932735283,
      "image_transformations_used": 120,
      "public_base_url": "https://blob.vertracloud.dev/k7p2m9x4qa",
      "limits": {
        "max_simple_upload_bytes": 104857600,
        "max_single_put_bytes": 104857600,
        "max_object_bytes": 10737418240,
        "min_part_bytes": 5242880,
        "max_part_bytes": 5368709120,
        "max_parts": 10000,
        "max_open_uploads": 4,
        "uploads_per_second": null,
        "max_rules": 10,
        "max_custom_domains": 3,
        "metadata_enabled": true,
        "share_password_enabled": true,
        "no_cache_enabled": false,
        "min_expiration_seconds": 604800,
        "image_transformations_per_month": 4000
      }
    }
  }
  ```
</ResponseExample>

### Error Responses

<ResponseField name="code" type="string">
  The error code indicating the reason for failure. Possible values:

  * `AUTH_TOKEN_MISSING` (`401`): No `Authorization` header was sent.
  * `API_KEY_INVALID` (`401`): The API key doesn't exist, was revoked, or its secret doesn't match.
  * `API_KEY_SCOPE_DENIED` (`403`): The key lacks the scope this route needs (`blob:read` or `blob:write`); `details.required` names it.
  * `WORKSPACE_PERMISSION_DENIED` (`403`): Only with `workspace_id`: you're not a member, or your role lacks the blob permission.
  * `WORKSPACE_NOT_FOUND` (`404`): Only with `workspace_id`: no workspace with that ID, or you're not a member.
</ResponseField>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>


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