> ## 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 SDK: prefix rules and usage stats

> Read and replace per-prefix Blob Storage rules with @squarecloud/blob (visibility, expiration, size, extensions, auto-delete) and read account usage stats.

Examples use the `blob` client from [Creating the client](/en/sdks/blob/client#creating-the-client).

## Rules

Rules set defaults and limits for every object under a prefix: visibility, expiration, maximum size, allowed extensions, cache and automatic deletion. They apply to every upload under the prefix, whether it comes from the SDK, an upload token or the dashboard. See [Update Settings](/en/blob-reference/endpoint/settings-put) for plan limits and matching.

### `rules.get()`

```typescript theme={"system"}
const rules = await blob.rules.get();
```

Returns the saved rules as an array. Each rule has the fields below plus `created_at`, and `active_from` when it has `delete_after_days`.

<Note>
  `active_from` is **optional**: the API only sends it for rules with `delete_after_days`. In TypeScript, handle it being `undefined`.
</Note>

### `rules.set(rules)`

```typescript theme={"system"}
await blob.rules.set([
    { prefix: "tmp/", delete_after_days: 7 },
    { prefix: "avatars/", max_size: 5 * 1024 * 1024, extensions: ["png", "jpg"] },
]);
```

<Warning>
  `rules.set()` **replaces the whole list**. Send every rule you want to keep; `rules.set([])` removes them all. To add one rule, read the list first:

  ```typescript theme={"system"}
  const current = await blob.rules.get();
  await blob.rules.set([
      ...current.map(({ created_at, active_from, ...rule }) => rule),
      { prefix: "exports/", expire: "30d" },
  ]);
  ```
</Warning>

It returns the saved list, like `rules.get()`.

| Field | Type | Description |
| - | - | - |
| `prefix` | `string` | Required. The prefix the rule applies to, e.g. `"a/b/"`. |
| `private` | `boolean` | Default visibility. |
| `expire` | `string` | Default expiration (`"30d"`, `"168h"`, ...). |
| `max_size` | `number` | Maximum file size in bytes, 512 B to 10 GiB. |
| `extensions` | `string[]` | 1 to 50 allowed extensions, matching `^[a-z0-9]{1,16}(\.[a-z0-9]{1,16})?$`. |
| `cache_control` | `string` | Default `Cache-Control`. |
| `delete_after_days` | `number` | Deletes objects this many days after they were written, 7 to 3650 (Enterprise from 1). |

<Warning>
  `delete_after_days` only takes effect **24 hours after the rule is saved** (see `active_from`). Once active, deleted objects cannot be recovered.
</Warning>

When a rule is rejected, the error's [`extra`](/en/sdks/blob/errors#squarecloudbloberror) carries the offending `prefix`:

```typescript theme={"system"}
import { SquareCloudBlobError } from "@squarecloud/blob";

try {
    await blob.rules.set(rules);
} catch (error) {
    if (error instanceof SquareCloudBlobError) {
        console.error(error.code, error.extra.prefix);
    }
}
```

<Note>
  `rules.get()` is a read and is [retried](/en/sdks/blob/errors#retry-policy). `rules.set()` gets a **single attempt**.
</Note>

## Stats

```typescript theme={"system"}
const stats = await blob.stats();

console.log(stats.usage.objects); // total objects
console.log(stats.usage.storage); // storage used, in bytes
```

| Field | Description |
| - | - |
| `usage.objects` | Number of objects. |
| `usage.storage` | Storage used, in bytes. |
| `plan.included` | Storage included in your plan, in bytes. |
| `billing` | `extraStorage`, `storagePrice`, `objectsPrice`, `totalEstimate`. |
| `month` | `days` and `average_storage` for the current month. |

<Info>
  Stats are an **estimate**, cached by the server for **60 seconds**. `billing` is only an estimate of the storage above your plan, not an invoice.
</Info>

See [Account Stats](/en/blob-reference/endpoint/stats).

## Next steps

<CardGroup cols={2}>
  <Card title="S3" icon="bucket" href="/en/sdks/blob/s3">
    Reach Blob Storage with any S3 client.
  </Card>

  <Card title="Settings API reference" icon="code" href="/en/blob-reference/endpoint/settings-put">
    The REST endpoints behind these methods.
  </Card>
</CardGroup>


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