# Usage (/en/docs/referencia/consumo)

Base: `https://api.facturia.cl/v1`. Every endpoint in this chapter authenticates with `Authorization: Bearer` unless stated otherwise, and the error envelope is the one in [Errors](/en/docs/errores).

| Method | Path                                   | What it does                       |
| ------ | -------------------------------------- | ---------------------------------- |
| `GET`  | [`/usage`](#get-usage)                 | Usage summary for a billing period |
| `GET`  | [`/usage/records`](#get-usage-records) | The immutable usage ledger         |

## `GET /usage` [#get-usage]

**Usage summary for a billing period**

Current-period request and emission counts against the account's plan limits.

```bash
curl -sS https://api.facturia.cl/v1/usage \
  -H "Authorization: Bearer $FACTURIA_KEY"
```

**Parameters**

| Parameter  | In    | Required | Type                              | Notes                                    |
| ---------- | ----- | -------- | --------------------------------- | ---------------------------------------- |
| `period`   | query | —        | Period                            | Tax period, `YYYY-MM`, America/Santiago. |
| `group_by` | query | —        | `empresa` · `tipo_dte` · `metric` |                                          |

**Responses**

| Code      | Meaning                                                                                                                                                                                                                                                                                                 | Body          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `200`     | The usage summary.                                                                                                                                                                                                                                                                                      | UsageSummary  |
| `401`     | Missing, malformed or revoked key.                                                                                                                                                                                                                                                                      | ErrorResponse |
| `403`     | Valid key, not permitted — scope, empresa allowlist, or mode.                                                                                                                                                                                                                                           | ErrorResponse |
| `429`     | Too many requests.                                                                                                                                                                                                                                                                                      | ErrorResponse |
| `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |

## `GET /usage/records` [#get-usage-records]

**The immutable usage ledger**

One record per accepted document. A document is recorded when the SII accepts it —
rejected, failed and sandbox documents never appear here. Corrections are compensating
records with negative quantity, never updates. This is a report, not a meter: the plan
is flat and unlimited, so nothing here is priced per document.

```bash
curl -sS https://api.facturia.cl/v1/usage/records \
  -H "Authorization: Bearer $FACTURIA_KEY"
```

**Parameters**

| Parameter     | In    | Required | Type                                                                        | Notes                                                   |
| ------------- | ----- | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------- |
| `limit`       | query | —        | integer                                                                     |                                                         |
| `cursor`      | query | —        | string                                                                      | Opaque cursor from a previous response's `next_cursor`. |
| `period`      | query | —        | Period                                                                      | Tax period, `YYYY-MM`, America/Santiago.                |
| `metric`      | query | —        | `document_accepted` · `received_document` · `f29_filing` · `empresa_active` |                                                         |
| `empresa_rut` | query | —        | Rut                                                                         |                                                         |

**Responses**

| Code      | Meaning                                                                                                                                                                                                                                                                                                 | Body                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `200`     | A list of usage records.                                                                                                                                                                                                                                                                                | lista de UsageRecord |
| `401`     | Missing, malformed or revoked key.                                                                                                                                                                                                                                                                      | ErrorResponse        |
| `403`     | Valid key, not permitted — scope, empresa allowlist, or mode.                                                                                                                                                                                                                                           | ErrorResponse        |
| `429`     | Too many requests.                                                                                                                                                                                                                                                                                      | ErrorResponse        |
| `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse        |