# space.highport.manage.getConsumption

> Published by [lexicons.highport.space](https://lexicon.garden/identity/did:plc:ciygg5hma4q7ah2kxaszkyob)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.getConsumption)
- [Documentation](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.getConsumption/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.getConsumption/examples)

## Definitions

### `space.highport.manage.getConsumption`

**Type**: `query`

The caller's bandwidth allowance for a period: granted, used, remaining, which entitlements contributed, and which domains may draw on it. One allowance covers both the caller's own sites and its visits to sender-pays sites.

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `period` | `string` | No | A UTC month as YYYY-MM. Defaults to the current month. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `approvals` | `array` | No | Domains the caller agreed to let spend its allowance, with the cap it chose for each. |
| `consumption` | `object` | Yes | One identity's allowance for one period. |

#### Errors

- **InvalidRequest**: period is not a UTC month formatted as YYYY-MM.

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "The caller's bandwidth allowance for a period: granted, used, remaining, which entitlements contributed, and which domains may draw on it. One allowance covers both the caller's own sites and its visits to sender-pays sites.",
      "errors": [
        {
          "description": "period is not a UTC month formatted as YYYY-MM.",
          "name": "InvalidRequest"
        }
      ],
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "approvals": {
              "description": "Domains the caller agreed to let spend its allowance, with the cap it chose for each.",
              "items": {
                "description": "Standing consent to spend the allowance on one domain.",
                "properties": {
                  "approvedAt": {
                    "description": "When the identity agreed.",
                    "format": "datetime",
                    "type": "string"
                  },
                  "capBytes": {
                    "description": "The cap the caller chose for this domain. Absent means no cap.",
                    "type": "integer"
                  },
                  "domain": {
                    "description": "The domain approved.",
                    "type": "string"
                  }
                },
                "required": [
                  "domain",
                  "approvedAt"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "consumption": {
              "description": "One identity's allowance for one period.",
              "properties": {
                "byDomain": {
                  "description": "Spend by domain.",
                  "items": {
                    "description": "Where the allowance was spent.",
                    "properties": {
                      "asVisitor": {
                        "description": "True when this was someone else's sender-pays site, not one of the caller's own.",
                        "type": "boolean"
                      },
                      "bytesBilled": {
                        "description": "Billed bytes.",
                        "type": "integer"
                      },
                      "domain": {
                        "description": "The domain.",
                        "type": "string"
                      }
                    },
                    "required": [
                      "domain",
                      "bytesBilled"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "entitledBytes": {
                  "description": "Bytes from entitlements.",
                  "type": "integer"
                },
                "entitlements": {
                  "items": {
                    "description": "One grant that adds to the allowance. The payment processor's reference is not exposed.",
                    "properties": {
                      "bytesPerPeriod": {
                        "description": "Bytes this entitlement adds per period.",
                        "type": "integer"
                      },
                      "endsAt": {
                        "description": "When it ends. Absent if it has no end date.",
                        "format": "datetime",
                        "type": "string"
                      },
                      "startsAt": {
                        "description": "When it started.",
                        "format": "datetime",
                        "type": "string"
                      }
                    },
                    "required": [
                      "bytesPerPeriod",
                      "startsAt"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "freeBytes": {
                  "description": "Bytes from the free grant.",
                  "type": "integer"
                },
                "freePerDomainBytes": {
                  "description": "The most the free grant can spend at any one domain this period. Purchased quota has no such cap. Zero means the free grant cannot be spent on other people's sites. This is why a reader can be refused at one domain while their allowance still has room.",
                  "type": "integer"
                },
                "grantedBytes": {
                  "description": "The free grant plus every active entitlement.",
                  "type": "integer"
                },
                "headerEstimateBytes": {
                  "description": "The fixed per-response header estimate included in usedBytes. The edge logs only response bodies, so every byte figure here is estimated by this much per response.",
                  "type": "integer"
                },
                "period": {
                  "description": "The UTC month, as YYYY-MM.",
                  "type": "string"
                },
                "periodEndsAt": {
                  "description": "When the allowance resets.",
                  "format": "datetime",
                  "type": "string"
                },
                "reconciledAt": {
                  "description": "When usedBytes was last reconciled against recorded requests. Absent for a period still in progress.",
                  "format": "datetime",
                  "type": "string"
                },
                "remainingBytes": {
                  "description": "What is left, never below zero.",
                  "type": "integer"
                },
                "usedBytes": {
                  "description": "Billable bytes spent so far.",
                  "type": "integer"
                }
              },
              "required": [
                "period",
                "periodEndsAt",
                "grantedBytes",
                "usedBytes",
                "remainingBytes",
                "freeBytes",
                "entitledBytes",
                "headerEstimateBytes"
              ],
              "type": "object"
            }
          },
          "required": [
            "consumption"
          ],
          "type": "object"
        }
      },
      "parameters": {
        "properties": {
          "period": {
            "description": "A UTC month as YYYY-MM. Defaults to the current month.",
            "type": "string"
          }
        },
        "type": "params"
      },
      "type": "query"
    }
  },
  "id": "space.highport.manage.getConsumption",
  "lexicon": 1
}
```