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

# Get print usage for this period

> Returns the plan, the live prints it includes this billing period, the live prints used so far (overage past the allowance on paid plans) and earlier periods. Lite periods are calendar months; paid periods follow the subscription's renewal date. Test mode jobs never count, so a test key sees the same live usage.



## OpenAPI

````yaml /openapi/openapi.json get /v1/usage
openapi: 3.1.0
info:
  contact:
    name: InkRelay
    url: https://docs.inkrelay.app
  description: >-
    Cloud printing API: send PDFs and raw jobs to printers attached to computers
    running the InkRelay agent.
  title: InkRelay API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.inkrelay.app
security:
  - ApiKeyAuth: []
  - BasicAuth: []
tags:
  - description: Who you are, your plan and usage
    name: Account
  - description: Machines running the InkRelay agent
    name: Computers
  - description: Printers reported by agents
    name: Printers
  - description: Submit and track print jobs
    name: Print jobs
  - description: Signed event delivery to your HTTPS endpoints
    name: Webhooks
  - description: Cursor based event feed
    name: Events
  - description: Prints used this period
    name: Usage
paths:
  /v1/usage:
    get:
      tags:
        - Usage
      summary: Get print usage for this period
      description: >-
        Returns the plan, the live prints it includes this billing period, the
        live prints used so far (overage past the allowance on paid plans) and
        earlier periods. Lite periods are calendar months; paid periods follow
        the subscription's renewal date. Test mode jobs never count, so a test
        key sees the same live usage.
      operationId: getUsage
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
          description: Usage of the current period
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid API key or session
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: The key scope or member role does not allow this
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: >-
            rate_limited: more than 20 requests per second with this API key;
            retry after the Retry-After header
          headers:
            RateLimit-Limit:
              description: Requests allowed per second for this API key (20)
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current one second window
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window frees a request
              schema:
                type: integer
            Retry-After:
              description: Whole seconds to wait before retrying; present on rate_limited
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
        - BasicAuth: []
components:
  schemas:
    Usage:
      example:
        history: []
        period:
          end: '2026-11-01T00:00:00.000Z'
          includedPrints: 5000
          overagePrints: 0
          start: '2026-10-01T00:00:00.000Z'
          usedPrints: 1234
        plan: essential
      properties:
        history:
          description: Earlier periods, newest first (up to 12)
          items:
            properties:
              end:
                description: First instant after the period (UTC), exclusive
                format: date-time
                type: string
              includedPrints:
                description: Live prints the plan includes
                type: integer
              overagePrints:
                description: >-
                  Live prints past the included allowance, billed as overage on
                  paid plans (always 0 on Lite)
                type: integer
              start:
                description: First instant of the period (UTC)
                format: date-time
                type: string
              usedPrints:
                description: Live print jobs created so far
                type: integer
            required:
              - start
              - end
              - includedPrints
              - usedPrints
            type: object
          type: array
        period:
          properties:
            end:
              description: First instant after the period (UTC), exclusive
              format: date-time
              type: string
            includedPrints:
              description: Live prints the plan includes
              type: integer
            overagePrints:
              description: >-
                Live prints past the included allowance, billed as overage on
                paid plans (always 0 on Lite)
              type: integer
            start:
              description: First instant of the period (UTC)
              format: date-time
              type: string
            usedPrints:
              description: Live print jobs created so far
              type: integer
          required:
            - start
            - end
            - includedPrints
            - usedPrints
          type: object
        plan:
          description: >-
            Current plan (lite, essential, standard or premium), as in GET
            /v1/whoami
          example: essential
          type: string
      required:
        - plan
        - period
        - history
      type: object
    Error:
      description: >-
        Every error response uses this envelope; code is stable, message is for
        humans.
      properties:
        error:
          properties:
            code:
              example: not_found
              type: string
            message:
              example: Printer not found
              type: string
            request_id:
              example: 4f9c2a7e-1b3d-4c5e-8f6a-0b1c2d3e4f5a
              type: string
            upgrade_url:
              description: Billing page to upgrade from; present on quota_exceeded
              example: https://app.inkrelay.app/billing?upgrade=1
              format: uri
              type: string
          required:
            - code
            - message
            - request_id
          type: object
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: ir_live_ or ir_test_ key
      description: >-
        Send `Authorization: Bearer <API key>`. Use an ir_test_ key in the
        playground; it only reaches virtual test printers.
      scheme: bearer
      type: http
      x-default: ir_test_REPLACE_WITH_YOUR_TEST_KEY
    BasicAuth:
      description: >-
        PrintNode compatible: put the API key in the username with an empty
        password
      scheme: basic
      type: http

````

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