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

# Get usage

> Usage cost by day, week, or month and by source, measured at included rates like the billing page. Defaults to the current billing period. Needs an admin's personal API key.



## OpenAPI

````yaml /openapi.json get /v1/organization/billing/usage
openapi: 3.1.0
info:
  title: Replicas API
  version: 2.0.0
  description: >-
    Create and control workspaces, and manage the environments, automations, and
    learnings they run with.
servers:
  - url: https://api.replicas.dev
    description: Production API
security:
  - apiKey: []
tags:
  - name: Replica
    description: >-
      A replica is a Replicas workspace: a cloud sandbox where a coding agent
      works on your repositories.
  - name: Chats
    description: Manage the agent chats inside a replica.
  - name: Message queue
    description: Messages waiting for the agent to finish its turn.
  - name: Commands and terminals
    description: Run commands and open shells in a replica.
  - name: Pull requests
    description: Inspect and act on pull requests a replica opened.
  - name: Previews
    description: Public URLs for ports in a replica.
  - name: Canvas
    description: Plans, reports, and other files agents produce.
  - name: Sharing
    description: Add replicas to members' Shared view.
  - name: Environments
    description: >-
      Environments define what a workspace starts with. A fork builds on the
      environments it was forked from.
  - name: Environment variables
    description: Variables injected into workspaces.
  - name: Environment files
    description: Files written into workspaces.
  - name: Environment skills
    description: Agent skills installed into workspaces.
  - name: Environment MCPs
    description: MCP servers available to workspace agents.
  - name: Hooks
    description: Scripts that run when warm pool snapshots build and when workspaces start.
  - name: Warm pools
    description: Pre-built workspaces that start faster.
  - name: Automations
    description: Run agents on schedules and events.
  - name: Repositories
    description: Repositories connected to the organization.
  - name: Learnings
    description: Organization skills every workspace agent loads.
  - name: Agent credentials
    description: >-
      API keys and endpoints that coding agents use. Connect Claude, Codex, and
      Muse subscriptions with the CLI.
  - name: Plugins
    description: Connect integrations that workspace agents can use.
  - name: Organization
    description: Who you are and who is in your organization.
  - name: Billing
    description: Credit left, usage limits, and usage cost.
  - name: Media
    description: Screenshots, recordings, and other files workspaces produce.
  - name: Slack
    description: Route Slack threads to workspaces.
  - name: Workspace identity
    description: OIDC keys for verifying workspace identity tokens.
paths:
  /v1/organization/billing/usage:
    get:
      tags:
        - Billing
      summary: Get usage
      description: >-
        Usage cost by day, week, or month and by source, measured at included
        rates like the billing page. Defaults to the current billing period.
        Needs an admin's personal API key.
      operationId: getBillingUsage
      parameters:
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - day
              - week
              - month
            default: day
        - name: start
          in: query
          description: ISO 8601 date. Defaults to the start of the current billing period.
          schema:
            type: string
            format: date-time
        - name: end
          in: query
          description: ISO 8601 date. Defaults to now.
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUsage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  parameters:
    ApiVersion:
      name: X-Replicas-Api-Version
      in: header
      description: >-
        API version. `2026-10-07` returns `snake_case` responses. See
        [versioning](/features/api#versioning).
      required: false
      schema:
        type: string
        enum:
          - '2026-10-07'
  schemas:
    BillingUsage:
      type: object
      properties:
        bucket:
          type: string
          enum:
            - day
            - week
            - month
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        points:
          type: array
          items:
            type: object
            properties:
              bucket:
                type: string
                format: date
              cents:
                type: integer
              by_source:
                type: object
                additionalProperties:
                  type: integer
                description: >-
                  Cents by source, like `dashboard`, `api`, `automation`,
                  `limrun`, or `modal`
            required:
              - bucket
              - cents
              - by_source
        sources:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              minutes:
                type: integer
              cents:
                type: integer
            required:
              - source
              - minutes
              - cents
        grants:
          type: array
          description: One-time credit for the current period
          items:
            type: object
            properties:
              amount_cents:
                type: integer
              reason:
                type: string
              granted_at:
                type: string
                format: date-time
            required:
              - amount_cents
              - reason
              - granted_at
      required:
        - bucket
        - start
        - end
        - points
        - sources
        - grants
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        details:
          type:
            - string
            - 'null'
          description: Additional error details
        code:
          type: string
          description: Machine-readable error code when available
      required:
        - error
  responses:
    BadRequest:
      description: Bad request - Missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden - The authenticated account cannot access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Organization or personal API key from **Settings → API Keys**.

````

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