> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Read current usage and permitted credit balances (beta)

> Returns the caller's existing billing-period usage and separately authorized credit balances. Unavailable sections are unknown, not zero. This read does not grant spending permission or change a budget.

Open Beta (This feature is currently in open beta. We are actively improving it based on your feedback. If you encounter any issues or have suggestions, please share them on our Discord community or visit the support page.)

> [tab] CLI Tool
>
> ```bash
> coderabbit api request /usage
> ```
>
> To install and sign in to the CLI, see [Call from the CLI](https://docs.coderabbit.ai/api/cli.md).

> [tab] MCP Server
>
> An agent connected to the [CodeRabbit MCP server](https://docs.coderabbit.ai/api/mcp.md) runs this operation as the `get_usage` tool. The connection selects the organization, so the arguments have no `org_id` or `org_name`.
>
> ```json
> {
>   "method": "tools/call",
>   "params": {
>     "name": "get_usage",
>     "arguments": {}
>   }
> }
> ```


## OpenAPI

````yaml /openapi.json get /v1/usage
openapi: 3.0.0
info:
  title: CodeRabbit API
  version: 1.0.0
  description: >-
    Read and manage CodeRabbit reviews, coding tasks, Verify, Triage, security
    findings, Knowledge Base, configuration, and users for your organization.
servers:
  - url: https://api.coderabbit.ai
    description: US region
  - url: https://api.eu.coderabbit.ai
    description: EU region
security:
  - ApiKeyAuth: []
tags:
  - name: Organizations and repositories
  - name: Pull requests and reviews
  - name: Coding Agent
  - name: Coding environments
  - name: Verify
  - name: Triage
  - name: Security
  - name: Knowledge Base
  - name: Automations
  - name: Reports
  - name: Configuration
  - name: Connections
  - name: Users and roles
  - name: Usage and metrics
paths:
  /v1/usage:
    get:
      tags:
        - Usage and metrics
      summary: Read current usage and permitted credit balances
      description: >-
        Returns the caller's existing billing-period usage and separately
        authorized credit balances. Unavailable sections are unknown, not zero.
        This read does not grant spending permission or change a budget.
      operationId: get_usage
      parameters:
        - name: org_id
          in: query
          schema:
            type: string
            minLength: 1
            description: >-
              Organization for a workspace key: the Git-provider organization ID
              (scope.provider_organization_id) or the CodeRabbit organization ID
              (scope.id, or id from list organizations). Supply either org_id or
              org_name, never both. Omit for organization keys and MCP
              connections.
          allowEmptyValue: true
          allowReserved: true
        - name: org_name
          in: query
          schema:
            type: string
            pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,38}$
            description: >-
              GitHub organization login, such as coderabbitai, not its display
              name. Matched case-insensitively within the authenticated
              workspace. Supply either org_name or org_id, never both; omit for
              organization keys and MCP connections.
          allowEmptyValue: true
          allowReserved: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformUsage'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - invalid_request
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - unauthenticated
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - forbidden
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - not_found
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - head_changed
                          - conflict
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '412':
          description: Precondition failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - precondition_failed
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '413':
          description: Content too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - payload_too_large
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - rate_limit_exceeded
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - internal_error
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - unavailable
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
components:
  schemas:
    PlatformUsage:
      type: object
      properties:
        organization:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
          required:
            - id
            - name
        billingPeriod:
          anyOf:
            - type: object
              properties:
                state:
                  enum:
                    - unavailable
                reason:
                  enum:
                    - forbidden
                    - lookup_failed
                    - not_supported
                    - not_available
                  type: string
              required:
                - state
                - reason
            - type: object
              properties:
                state:
                  enum:
                    - available
                scope:
                  enum:
                    - user
                usageBillingConfigured:
                  type: boolean
                usageBillingActive:
                  type: boolean
                callerUsage:
                  anyOf:
                    - type: object
                      properties:
                        login:
                          type: string
                        reviewsCount:
                          type: integer
                          minimum: 0
                        spendCents:
                          type: integer
                          minimum: 0
                        waivedCents:
                          type: integer
                          minimum: 0
                      required:
                        - login
                        - reviewsCount
                        - spendCents
                        - waivedCents
                    - type: string
                      nullable: true
                      enum:
                        - null
                resetsAt:
                  anyOf:
                    - type: string
                    - type: string
                      nullable: true
                      enum:
                        - null
                reviewSpendingCap:
                  anyOf:
                    - type: object
                      properties:
                        limitCents:
                          anyOf:
                            - type: integer
                              minimum: 0
                            - type: string
                              nullable: true
                              enum:
                                - null
                        isActive:
                          type: boolean
                      required:
                        - limitCents
                        - isActive
                    - type: string
                      nullable: true
                      enum:
                        - null
              required:
                - state
                - scope
                - usageBillingConfigured
                - usageBillingActive
                - callerUsage
                - resetsAt
                - reviewSpendingCap
        credits:
          type: object
          properties:
            prepaid:
              anyOf:
                - type: object
                  properties:
                    state:
                      enum:
                        - unavailable
                    reason:
                      enum:
                        - forbidden
                        - lookup_failed
                        - not_supported
                        - not_available
                      type: string
                  required:
                    - state
                    - reason
                - type: object
                  properties:
                    state:
                      enum:
                        - available
                    scope:
                      enum:
                        - subscription
                    reviewAvailableCents:
                      type: integer
                      minimum: 0
                    enrolled:
                      type: boolean
                  required:
                    - state
                    - scope
                    - reviewAvailableCents
            legacyCli:
              anyOf:
                - type: object
                  properties:
                    state:
                      enum:
                        - unavailable
                    reason:
                      enum:
                        - forbidden
                        - lookup_failed
                        - not_supported
                        - not_available
                      type: string
                  required:
                    - state
                    - reason
                - type: object
                  properties:
                    state:
                      enum:
                        - available
                    scope:
                      enum:
                        - subscription
                    balanceCents:
                      type: integer
                      minimum: 0
                  required:
                    - state
                    - scope
                    - balanceCents
          required:
            - prepaid
            - legacyCli
        includedReviews:
          type: object
          properties:
            state:
              enum:
                - unavailable
            reason:
              enum:
                - forbidden
                - lookup_failed
                - not_supported
                - not_available
              type: string
          required:
            - state
            - reason
      required:
        - organization
        - billingPeriod
        - credits
        - includedReviews
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-coderabbitai-api-key
      description: >-
        See [Authentication](/api/authentication) for the key types and where to
        create a key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.