# Get account usage

`GET /api/usage`

Returns the account plan, UTC-month accepted-message allowance, custom domains, exact-address routes, storage quota and current retention setting.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `usage:read`.

Audience: management.

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "usage": {
      "$ref": "#/components/schemas/Usage"
    }
  },
  "required": [
    "usage"
  ]
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 404

Account not found.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503



## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/Usage

```json
{
  "type": "object",
  "properties": {
    "plan": {
      "$ref": "#/components/schemas/Plan"
    },
    "retention": {
      "type": "object",
      "description": "Current account retention policy. Changes apply to existing and newly accepted messages.",
      "properties": {
        "retentionDays": {
          "type": "integer",
          "minimum": 0
        },
        "maxDays": {
          "type": "integer",
          "minimum": 1
        },
        "configuredDays": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        }
      },
      "required": [
        "retentionDays",
        "maxDays",
        "configuredDays"
      ]
    },
    "period": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "format": "date-time"
        },
        "resetsAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "start",
        "resetsAt"
      ]
    },
    "messages": {
      "type": "object",
      "properties": {
        "accepted": {
          "type": "integer"
        },
        "reserved": {
          "type": "integer"
        },
        "limit": {
          "type": "integer"
        },
        "remaining": {
          "type": "integer"
        },
        "status": {
          "type": "string",
          "enum": [
            "available",
            "approaching",
            "reached"
          ]
        }
      },
      "required": [
        "accepted",
        "reserved",
        "limit",
        "remaining",
        "status"
      ]
    },
    "domains": {
      "type": "object",
      "properties": {
        "used": {
          "type": "integer"
        },
        "limit": {
          "type": [
            "integer",
            "null"
          ]
        },
        "remaining": {
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "used",
        "limit",
        "remaining"
      ]
    },
    "addressRoutes": {
      "type": "object",
      "properties": {
        "used": {
          "type": "integer"
        },
        "limit": {
          "type": [
            "integer",
            "null"
          ]
        },
        "remaining": {
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "used",
        "limit",
        "remaining"
      ]
    },
    "storage": {
      "$ref": "#/components/schemas/StorageUsage"
    }
  },
  "required": [
    "plan",
    "retention",
    "period",
    "messages",
    "domains",
    "addressRoutes",
    "storage"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```

### #/components/schemas/Plan

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "offered": {
      "type": "boolean"
    },
    "monthlyPriceEur": {
      "type": [
        "number",
        "null"
      ]
    },
    "customDomains": {
      "type": [
        "integer",
        "null"
      ]
    },
    "monthlyMessages": {
      "type": "integer"
    },
    "rawMessageLimitBytes": {
      "type": "integer"
    },
    "retentionDays": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum content retention for this plan. Account settings may select 0 days or any whole number of days from 1 through this maximum."
    },
    "storageLimitBytes": {
      "type": "integer",
      "minimum": 0,
      "description": "Current retained storage capacity in bytes. One GB is 1,000,000,000 bytes."
    },
    "artifactDownloadLimitBytes": {
      "type": "integer",
      "description": "Informational plan value in bytes. It is not an enforced monthly attachment-download limit."
    },
    "perAddressRoutes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    }
  },
  "required": [
    "id",
    "name",
    "offered",
    "monthlyPriceEur",
    "customDomains",
    "monthlyMessages",
    "rawMessageLimitBytes",
    "retentionDays",
    "storageLimitBytes",
    "artifactDownloadLimitBytes",
    "perAddressRoutes"
  ]
}
```

### #/components/schemas/StorageUsage

```json
{
  "type": "object",
  "properties": {
    "rawBytes": {
      "type": "integer"
    },
    "artifactBytes": {
      "type": "integer"
    },
    "retainedBytes": {
      "type": "integer"
    },
    "reservedBytes": {
      "type": "integer"
    },
    "limitBytes": {
      "type": "integer"
    },
    "remainingBytes": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "available",
        "approaching",
        "reached"
      ]
    }
  },
  "required": [
    "rawBytes",
    "artifactBytes",
    "retainedBytes",
    "reservedBytes",
    "limitBytes",
    "remainingBytes",
    "status"
  ]
}
```
