> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. # List account limits and usage > Retrieves the effective limits and current usage for an account. Monetary values use USD cents, and count-based limits use whole-number counts. Transaction limits do not include `window`, `currentAggregate`, or `usagePercent`. Aggregate fields can also be omitted when a usage source is unavailable. ## OpenAPI ````yaml openapi/accounts.yaml get /v1/accounts/{accountId}/limits/usage openapi: 3.0.2 info: version: 1.0.0 title: Accounts (Stablecoin) API description: > Circle's Accounts API provides endpoints for managing stablecoin accounts -- including transfers, withdrawals, deposits, wire and ACH bank accounts, and blockchain addresses. An **Account** is a general representation of a ledger or custody object that holds balances. It can be a business account, a stablecoin account ledger for an end user, an extra sub-ledger, or any future custody solution. license: name: Circle License url: https://circle.com/terms servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Accounts description: Manage accounts. - name: Account Groups description: Manage custody account groups and their memberships. - name: Transactions description: | Get a unified, customer-friendly view of account transaction activity. - name: Transfers description: Manage account transfers. - name: Withdrawals description: Manage account bank withdrawals (fiat offramp). - name: Wires description: Manage account bank accounts for wire transfers. - name: ACH description: Manage account bank accounts for ACH transfers. - name: Deposits description: Get information on account bank deposits. - name: Deposit Addresses description: Manage account deposit addresses. - name: Recipient Addresses description: Manage account recipient addresses used for transfers. - name: Limits description: View effective account limits and current usage. paths: /v1/accounts/{accountId}/limits/usage: get: tags: - Limits summary: List account limits and usage description: > Retrieves the effective limits and current usage for an account. Monetary values use USD cents, and count-based limits use whole-number counts. Transaction limits do not include `window`, `currentAggregate`, or `usagePercent`. Aggregate fields can also be omitted when a usage source is unavailable. operationId: listAccountLimitsUsage parameters: - $ref: '#/components/parameters/AccountPathId' - name: operation in: query required: false description: Filter results by limit operation. schema: $ref: '#/components/schemas/LimitOperation' - name: assetType in: query required: false description: > Filter results by asset type. When combined with `operation`, the asset type must be valid for that operation. schema: $ref: '#/components/schemas/LimitAssetType' - name: window in: query required: false description: > Filter results by rolling-window duration in ISO 8601 format. Transaction limits are excluded when this filter is present. The `PT24H` window is not supported with `operation=fiat_linking` or `operation=deposit_return_count`; these combinations return a `400` response. Use `P30D` for those operations. schema: $ref: '#/components/schemas/LimitWindow' responses: '200': description: Successfully retrieved zero or more matching account limits. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ListAccountLimitsUsageResponse' example: data: type: limitsUsage accountId: '1000662322' currency: USD watermark: '2026-05-12T10:29:58.000Z' items: - operation: send assetType: crypto comparisonType: transaction unit: usd_cents effectiveThreshold: 1000000 - operation: send assetType: crypto comparisonType: aggregation window: PT24H unit: usd_cents effectiveThreshold: 5000000 currentAggregate: 1234567 usagePercent: 24.69 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: parameters: AccountPathId: name: accountId description: Identifier of the account. in: path required: true schema: type: string example: '1000565227' schemas: LimitOperation: type: string description: The account activity or control to which the limit applies. enum: - deposit - withdrawal - receive - send - send_count - address_linking - fiat_linking - deposit_return_count - balance_cap example: send LimitAssetType: type: string description: The asset class to which the limit applies. enum: - fiat - crypto example: crypto LimitWindow: type: string description: Rolling-window duration in ISO 8601 format. enum: - PT24H - P30D example: PT24H ListAccountLimitsUsageResponse: title: ListAccountLimitsUsageResponse type: object required: - data properties: data: $ref: '#/components/schemas/AccountLimitsUsage' XRequestId: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde AccountLimitsUsage: type: object required: - type - accountId - currency - watermark - items properties: type: type: string description: Resource type. This value is always `limitsUsage`. enum: - limitsUsage example: limitsUsage accountId: type: string description: Identifier of the account whose limits were requested. pattern: ^\d{1,10}$ example: '1000662322' currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency used for monetary limits. example: USD watermark: type: string format: date-time description: > Freshness boundary for the aggregate values in this response. Events after this timestamp are not included in `currentAggregate`. example: '2026-05-12T10:29:58.000Z' items: type: array description: Effective limits and current usage matching the request filters. items: $ref: '#/components/schemas/AccountLimitUsage' Error: type: object required: - code - message properties: code: type: integer description: > Circle internal status code from the platform `CoreStatusCode` enum (and its domain-specific extensions). **This is not the HTTP status code** — `-1` is the catch-all unknown error, `1`/`2` indicate API parameter problems, `3` is forbidden, `4` is unauthorized, and larger values identify domain-specific failures. Consumers should rely on the HTTP status line for transport-level error class and on this field for the specific Circle error case. example: 2 message: type: string description: >- Internal error message; suitable for logging but not for end-user display. example: API parameter invalid. externalMessage: type: string description: > End-user-displayable error message. Present when the server has generated a customer-facing variant for this error; omitted otherwise. example: The provided amount exceeds the maximum allowed. errors: type: array description: Additional request-field validation errors, when available. items: $ref: '#/components/schemas/ErrorDetail' AccountLimitUsage: type: object required: - operation - assetType - comparisonType - unit - effectiveThreshold properties: operation: $ref: '#/components/schemas/LimitOperation' assetType: $ref: '#/components/schemas/LimitAssetType' comparisonType: $ref: '#/components/schemas/LimitComparisonType' window: allOf: - $ref: '#/components/schemas/LimitWindow' description: Present only for limits evaluated over a rolling window. unit: $ref: '#/components/schemas/LimitUnit' effectiveThreshold: type: integer format: int64 minimum: 0 description: Effective limit for the account, expressed in the declared `unit`. example: 5000000 currentAggregate: type: integer format: int64 minimum: 0 description: > Current rolling usage in the declared `unit`. Omitted for transaction limits and when an aggregate source cannot provide current usage. Do not treat an omitted value as zero. example: 1234567 usagePercent: type: number minimum: 0 description: > Percentage of the effective threshold currently used, rounded to two decimal places. This value can exceed 100 and is omitted when `currentAggregate` is unavailable or the threshold is zero. example: 24.69 ErrorDetail: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. example: invalid_value location: type: string description: Query parameter or request field that caused the error. example: assetType message: type: string description: Human-readable description of the specific error. example: The operation and assetType combination is invalid. LimitComparisonType: type: string description: > How the limit is evaluated. `transaction` applies to each transaction, while `aggregation` applies to usage accumulated over a rolling window. enum: - transaction - aggregation example: aggregation LimitUnit: type: string description: > Unit used by `effectiveThreshold` and `currentAggregate`. `usd_cents` represents USD minor units, and `count` represents a whole-number event count. enum: - usd_cents - count example: usd_cents headers: XRequestId: description: > Circle-generated universally unique identifier (UUID v4). Useful for identifying a specific request when communicating with Circle Support. schema: $ref: '#/components/schemas/XRequestId' responses: BadRequest: description: The request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 2 message: API parameter invalid. NotAuthorized: description: >- The request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 4 message: Unauthorized. Forbidden: description: The API key does not have permission to access this resource. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 3 message: Missing permission. NotFound: description: The specified resource was not found. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: Not found. InternalServerError: description: >- The server encountered an unexpected condition that prevented it from fulfilling the request. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1 message: 'Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4' securitySchemes: bearerAuth: type: http scheme: bearer ````