# Check usage

Source: https://docs.orbytelabs.com/api-reference/events/checkUsage

## POST /v1/check

```json
{
  "operationId": "checkUsage",
  "summary": "Check usage",
  "description": "Checks subscription allowances and the current credit balance without reserving usage or credits. Tracking enforces both again atomically.",
  "tags": [
    "Events"
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "identity": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "feature": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "amountNanocredits": {
              "type": "string",
              "maxLength": 19,
              "pattern": "^(0|[1-9][0-9]*)$"
            },
            "occurredAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "entityId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "quantity": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991,
              "default": 1
            }
          },
          "required": [
            "identity",
            "feature"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Current affordability, charge, and credit balance",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "allowed": {
                "type": "boolean"
              },
              "creditKey": {
                "type": "string"
              },
              "amountNanocredits": {
                "type": "string",
                "maxLength": 19,
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "balanceNanocredits": {
                "type": "string",
                "maxLength": 19,
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "periodStart": {
                "type": "number"
              },
              "periodEnd": {
                "type": "number"
              },
              "limit": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "number"
                  },
                  "used": {
                    "type": "number"
                  },
                  "remaining": {
                    "type": "number"
                  },
                  "periodStart": {
                    "type": "number"
                  },
                  "periodEnd": {
                    "type": "number"
                  },
                  "overage": {
                    "type": "string",
                    "enum": [
                      "block",
                      "credits"
                    ]
                  }
                },
                "required": [
                  "limit",
                  "used",
                  "remaining",
                  "periodStart",
                  "periodEnd",
                  "overage"
                ],
                "additionalProperties": false
              },
              "reason": {
                "type": "string",
                "enum": [
                  "feature_limit_exceeded",
                  "subscription_inactive",
                  "insufficient_balance"
                ]
              }
            },
            "required": [
              "allowed",
              "creditKey",
              "amountNanocredits",
              "balanceNanocredits"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "401": {
      "description": "Missing, expired, or revoked API key",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "403": {
      "description": "Insufficient permission or unsupported key kind",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "404": {
      "description": "Resource not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "409": {
      "description": "Conflict or insufficient balance",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "413": {
      "description": "Body exceeds 16 KiB",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "415": {
      "description": "Content-Type must be application/json",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "422": {
      "description": "Unsupported pricing or billing configuration",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded; see Retry-After",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "message"
            ],
            "additionalProperties": false
          }
        }
      }
    }
  }
}
```

Complete schema: [OpenAPI 3.1 document](https://docs.orbytelabs.com/openapi.json)