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

# Get usage and recent charges

> Reads Deepline usage for the authenticated workspace. Use run_id for one run or request_id for one exact call. Pending holds are not final charges. Recent activity is a bounded view; use the ledger for longer history. Responses are private and uncached.

Authentication: workspace API key in `Authorization: Bearer <key>`.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid input or incompatible filters. Correct the request before retrying. |
| 401 | Missing or invalid workspace authentication. |
| 404 | The requested resource was not found in the authenticated workspace. |
| 500 | Server failure. Retry this read; it does not start new work. |


## OpenAPI

````yaml openapi.json GET /api/v2/billing/usage
openapi: 3.1.1
info:
  title: Deepline API
  version: v2
  description: >-
    Discover typed GTM tools and callable Plays, then execute a tool or start
    and inspect a durable Deepline Play run. Use the MCP endpoint when your
    client supports Model Context Protocol.
  contact:
    name: Deepline support
    email: team@deepline.com
    url: https://deepline.com/contact
servers:
  - url: https://code.deepline.com
    description: Deepline production runtime API
security: []
tags:
  - name: Health
    description: Availability checks.
  - name: Billing
    description: Safe recovery of existing purchase intent.
  - name: Tools
    description: Discover and execute typed provider tools.
  - name: Plays
    description: Discover, start, and inspect durable Play runs.
externalDocs:
  description: API reference
  url: https://deepline.com/docs/api-reference
paths:
  /api/v2/billing/usage:
    get:
      tags:
        - Billing
      summary: Get usage and recent charges
      description: >-
        Reads Deepline usage for the authenticated workspace. Use run_id for one
        run or request_id for one exact call. Pending holds are not final
        charges. Recent activity is a bounded view; use the ledger for longer
        history. Responses are private and uncached.
      operationId: getBillingUsage
      parameters:
        - name: run_id
          in: query
          description: >-
            Filter recent charges and include spend for this exact public run
            ID.
          schema:
            type: string
        - name: request_id
          in: query
          description: >-
            Exact call lookup, at most 200 characters. Cannot be combined with
            run_id, recent_cursor, or recent_offset. Returns only org_id and
            recent.
          schema:
            type: string
        - name: recent_limit
          in: query
          description: >-
            Recent page size; default 10, clamped to 100. Ignored for
            request_id.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: recent_offset
          in: query
          description: >-
            Zero-based recent activity offset, at most 500. Follow
            recent.next_offset while recent.has_more is true.
          schema:
            type: integer
            minimum: 0
            maximum: 500
            default: 0
        - name: recent_cursor
          in: query
          description: >-
            Legacy cursor input. Prefer recent_offset; cannot be combined with
            request_id.
          schema:
            type: string
      responses:
        '200':
          description: Usage summary with recent activity, or the exact request lookup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  org_id:
                    type: string
                  balance:
                    type: number
                  balance_display:
                    type: string
                  rough_usd_balance:
                    type: number
                  balance_updated_at:
                    type:
                      - string
                      - 'null'
                  plan:
                    type: object
                    properties:
                      public_name:
                        type: string
                      usd_per_credit:
                        type: number
                    required:
                      - public_name
                      - usd_per_credit
                  managed_usd_per_email:
                    type:
                      - number
                      - 'null'
                  has_payment_method:
                    type: boolean
                  payment_method:
                    type:
                      - object
                      - 'null'
                    additionalProperties: true
                  usage:
                    type: object
                    properties:
                      month_spent_credits:
                        type: number
                      rough_usd_spent:
                        type: number
                      last_30_days_usage_credits:
                        type: number
                      rough_usd_last_30_days_usage:
                        type: number
                      temporary_hold_credits:
                        type: number
                      temporary_hold_credits_truncated:
                        type: boolean
                      rough_usd_temporary_holds:
                        type: number
                      period_start_at:
                        type: string
                      period_end_at:
                        type: string
                    required:
                      - month_spent_credits
                      - rough_usd_spent
                      - last_30_days_usage_credits
                      - rough_usd_last_30_days_usage
                      - temporary_hold_credits
                      - temporary_hold_credits_truncated
                      - rough_usd_temporary_holds
                      - period_start_at
                      - period_end_at
                  run:
                    type:
                      - object
                      - 'null'
                    properties:
                      run_id:
                        type: string
                      spent_credits:
                        type: number
                      rough_usd_spent:
                        type: number
                      event_count:
                        type: number
                  quota:
                    type: object
                    properties:
                      enabled:
                        type: boolean
                      monthly_credits_limit:
                        type:
                          - number
                          - 'null'
                      monthly_rough_usd_limit:
                        type:
                          - number
                          - 'null'
                      remaining_credits:
                        type:
                          - number
                          - 'null'
                      remaining_rough_usd:
                        type:
                          - number
                          - 'null'
                      updated_at:
                        type:
                          - string
                          - 'null'
                    required:
                      - enabled
                      - monthly_credits_limit
                      - monthly_rough_usd_limit
                      - remaining_credits
                      - remaining_rough_usd
                      - updated_at
                  autobill:
                    type: object
                    description: >-
                      Automatic recharge availability and settings; the fields
                      depend on the workspace’s billing terms.
                    additionalProperties: true
                  recent:
                    type: object
                    properties:
                      run_id:
                        type:
                          - string
                          - 'null'
                      request_id:
                        type: string
                      total:
                        type: number
                      total_is_exact:
                        type: boolean
                        description: >-
                          True only when total covers the complete matching
                          history.
                      total_lower_bound:
                        type: number
                      offset:
                        type: number
                      limit:
                        type: number
                      next_offset:
                        type: number
                      next_cursor:
                        type:
                          - string
                          - 'null'
                      has_more:
                        type: boolean
                      incomplete:
                        type: boolean
                        description: >-
                          True when the available page walk cannot establish
                          complete history.
                      entries:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            provider:
                              type: string
                            operation:
                              type: string
                            status:
                              type: string
                            request_id:
                              type: string
                            run_id:
                              type:
                                - string
                                - 'null'
                            play_run_id:
                              type:
                                - string
                                - 'null'
                            workflow_id:
                              type:
                                - string
                                - 'null'
                            billing_run_id:
                              type:
                                - string
                                - 'null'
                            execution_run_id:
                              type:
                                - string
                                - 'null'
                            included_in_run_id:
                              type:
                                - string
                                - 'null'
                            billing_scope:
                              type:
                                - string
                                - 'null'
                            step_block_id:
                              type:
                                - string
                                - 'null'
                            step_alias:
                              type:
                                - string
                                - 'null'
                            auth_type:
                              type:
                                - string
                                - 'null'
                            user_id:
                              type:
                                - string
                                - 'null'
                            api_key_id:
                              type:
                                - string
                                - 'null'
                            credits:
                              type: number
                            billing_mode:
                              type:
                                - string
                                - 'null'
                            pricing_model:
                              type:
                                - string
                                - 'null'
                            pricing_basis:
                              type:
                                - string
                                - 'null'
                            pricing_unit_amount:
                              type:
                                - number
                                - 'null'
                            outcome:
                              type:
                                - string
                                - 'null'
                            policy_id:
                              type:
                                - string
                                - 'null'
                            provider_units:
                              type:
                                - number
                                - 'null'
                            batch_count:
                              type:
                                - number
                                - 'null'
                            total_results:
                              type:
                                - number
                                - 'null'
                            delta:
                              type:
                                - number
                                - 'null'
                            reason:
                              type:
                                - string
                                - 'null'
                            stripe_session_id:
                              type:
                                - string
                                - 'null'
                            metadata:
                              type:
                                - object
                                - 'null'
                              additionalProperties: true
                            billing_note:
                              type:
                                - string
                                - 'null'
                            charge_state:
                              type: string
                              enum:
                                - posted
                                - temporary_hold
                                - hold_release
                                - pending
                                - free
                                - failed
                            charge_finality:
                              type: string
                              enum:
                                - final
                                - pending
                                - unknown
                            rough_usd_cost:
                              type:
                                - number
                                - 'null'
                              description: Null for pending charges or unknown finality.
                            created_at:
                              type: string
                          required:
                            - id
                            - provider
                            - operation
                            - status
                            - request_id
                            - run_id
                            - credits
                            - charge_state
                    required:
                      - run_id
                      - total
                      - offset
                      - limit
                      - next_offset
                      - next_cursor
                      - has_more
                      - incomplete
                      - entries
                required:
                  - org_id
                  - recent
              example:
                org_id: org_example
                recent:
                  run_id: null
                  request_id: request_example
                  total: 1
                  total_is_exact: true
                  total_lower_bound: 1
                  offset: 0
                  limit: 1
                  next_offset: 1
                  next_cursor: null
                  has_more: false
                  incomplete: false
                  entries:
                    - id: usage_example
                      provider: free
                      operation: simple_company_search
                      status: completed
                      request_id: request_example
                      run_id: null
                      credits: 0
                      charge_state: free
                      charge_finality: final
                      rough_usd_cost: 0
        '400':
          description: >-
            Invalid input or incompatible filters. Correct the request before
            retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid workspace authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized
        '404':
          description: The requested resource was not found in the authenticated workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server failure. Retry this read; it does not start new work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          oneOf:
            - type: string
              description: Route-specific error message.
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                resolution:
                  type: string
              additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Deepline workspace API key
      description: >-
        Create a workspace API key in the Deepline dashboard before calling
        authenticated endpoints.

````

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