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

# Get Usage Statistics

> For direct client keys, returns usage for the associated company. For ATS keys, returns aggregated usage across ATS-managed companies. Test interviews (created with isTest=true) are excluded from billing and usage summaries.

Retrieves usage statistics for the API key's company, including total minutes or credits consumed, interview counts, and breakdown by cost key. Behavior differs between regular API keys and ATS integration keys, and between companies on the **minutes** and **credits** billing systems.

## Overview

The get usage endpoint provides read-only access to billing and usage information. For regular API keys, it returns usage for the associated company. For ATS keys, it returns aggregated usage across all companies managed by that ATS key.

Each company in the response carries a `billingSystem` field indicating which unit it is billed in:

* `"minutes"` — legacy interview-minutes accounting. `totalMinutesUsed` and `breakdownByCostKey[].minutesUsed` are populated; `totalCreditsUsed` and `creditsUsed` are omitted entirely.
* `"credits"` — per-product credits accounting. `totalCreditsUsed` and `breakdownByCostKey[].creditsUsed` are populated; `totalMinutesUsed` and `minutesUsed` are omitted entirely.

## Date Range Parameters

You can specify a date range for usage data:

```javascript theme={null}
// Last 30 days (default)
GET /billing/usage

// Custom date range
GET /billing/usage?start=2024-01-01&end=2024-01-31
```

* `start` (optional): Start date in ISO 8601 format (defaults to 30 days ago)
* `end` (optional): End date in ISO 8601 format (defaults to current date)

## Regular API Keys (Minutes-Based Company)

For minutes-based companies, the response reports usage in interview minutes:

```json theme={null}
{
  "data": {
    "companies": [
      {
        "companyId": "company-uuid",
        "companyName": "Your Company",
        "billingSystem": "minutes",
        "totalMinutesUsed": 245.5,
        "totalInterviews": 42,
        "breakdownByCostKey": [
          {
            "costKey": "interview_minutes",
            "minutesUsed": 245.5,
            "events": 42
          }
        ]
      }
    ],
    "totalMinutesUsed": 245.5,
    "totalInterviews": 42,
    "breakdownByCostKey": [
      {
        "costKey": "interview_minutes",
        "minutesUsed": 245.5,
        "events": 42
      }
    ]
  }
}
```

## Regular API Keys (Credits-Based Company)

For credits-based companies, the response reports usage in credits. Minutes-related fields are omitted entirely:

```json theme={null}
{
  "data": {
    "companies": [
      {
        "companyId": "company-uuid",
        "companyName": "Your Company",
        "billingSystem": "credits",
        "totalCreditsUsed": 612.5,
        "totalInterviews": 42,
        "breakdownByCostKey": [
          {
            "costKey": "interview_minutes",
            "creditsUsed": 612.5,
            "events": 42
          }
        ]
      }
    ],
    "totalCreditsUsed": 612.5,
    "totalInterviews": 42,
    "breakdownByCostKey": [
      {
        "costKey": "interview_minutes",
        "creditsUsed": 612.5,
        "events": 42
      }
    ]
  }
}
```

## ATS Integration Keys

For ATS keys, the response includes aggregated usage across all companies managed by the ATS.

```json theme={null}
{
  "data": {
    "companies": [
      {
        "companyId": "company-a-uuid",
        "companyName": "Client Company A",
        "billingSystem": "minutes",
        "totalMinutesUsed": 120.0,
        "totalInterviews": 20,
        "breakdownByCostKey": [
          { "costKey": "interview_minutes", "minutesUsed": 120.0, "events": 20 }
        ]
      },
      {
        "companyId": "company-b-uuid",
        "companyName": "Client Company B",
        "billingSystem": "minutes",
        "totalMinutesUsed": 80.5,
        "totalInterviews": 22,
        "breakdownByCostKey": [
          { "costKey": "interview_minutes", "minutesUsed": 80.5, "events": 22 }
        ]
      }
    ],
    "totalMinutesUsed": 200.5,
    "totalInterviews": 42,
    "breakdownByCostKey": [
      { "costKey": "interview_minutes", "minutesUsed": 200.5, "events": 42 }
    ]
  }
}
```

## Use Cases

* **Usage Monitoring**: Track interview minutes / credits and interview counts
* **Cost Tracking**: Monitor usage against subscription limits
* **Billing Reporting**: Generate usage reports for billing purposes
* **Multi-Tenant Analytics**: Track usage per company for ATS platforms

## Response Structure

The response includes:

* **companies**: Array of company-level usage (single item for regular keys, multiple for ATS keys).
* **billingSystem** *(per company)*: Either `"minutes"` or `"credits"`.
* **totalMinutesUsed**: Total interview minutes consumed in the period. Present when at least one company in scope is on the minutes billing system; omitted otherwise.
* **totalCreditsUsed**: Total credits consumed in the period. Present when at least one company in scope is on the credits billing system; omitted otherwise.
* **totalInterviews**: Total number of interviews conducted.
* **breakdownByCostKey**: Array of usage buckets. Each entry includes `costKey` and `events`, plus `minutesUsed` *or* `creditsUsed` depending on the company's billing system. Cross-system fields are never present in a per-company breakdown.

## Monitoring Usage

```javascript theme={null}
async function checkUsageStatus() {
  const response = await fetch("https://api.instaview.sk/billing/usage", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  const { data } = await response.json();

  data.companies.forEach((company) => {
    if (company.billingSystem === "credits") {
      console.log(
        `${company.companyName}: ${company.totalCreditsUsed} credits`,
      );
    } else {
      console.log(`${company.companyName}: ${company.totalMinutesUsed} min`);
    }
  });

  return data;
}
```

## Required Scope

<Info>
  **Required Scope**: `read:billing` is required to access this endpoint. Ensure
  your API key has this scope enabled.
</Info>

## Related Resources

<CardGroup cols={2}>
  <Card title="Billing Resource Guide" icon="credit-card" href="/guides/resources/billing">
    Comprehensive guide to billing, usage tracking, and subscription management
  </Card>

  <Card title="Scopes & Permissions" icon="shield" href="/guides/scopes-and-permissions">
    Learn about required scopes
  </Card>

  <Card title="ATS Integration" icon="plug" href="/guides/ats-integration">
    Understand ATS key usage aggregation
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /billing/usage
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /billing/usage:
    get:
      tags:
        - Billing
      summary: Get usage statistics for the API key's company
      description: >-
        For direct client keys, returns usage for the associated company. For
        ATS keys, returns aggregated usage across ATS-managed companies. Test
        interviews (created with isTest=true) are excluded from billing and
        usage summaries.
      operationId: PublicBillingController_getUsage_v1
      parameters:
        - name: start
          required: false
          in: query
          description: Start of the billing period (inclusive), ISO 8601
          schema:
            example: '2025-01-01T00:00:00.000Z'
            type: string
        - name: end
          required: false
          in: query
          description: End of the billing period (exclusive), ISO 8601
          schema:
            example: '2025-01-31T00:00:00.000Z'
            type: string
        - name: companyId
          required: false
          in: query
          description: >-
            Required for ATS API keys to specify which company to access.
            Ignored for standard company API keys.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAtsUsageSummaryDto'
      security:
        - bearer: []
components:
  schemas:
    PublicAtsUsageSummaryDto:
      type: object
      properties:
        companies:
          description: Per-company usage details for all companies visible to this ATS key
          type: array
          items:
            $ref: '#/components/schemas/PublicCompanyUsageDto'
        totalMinutesUsed:
          type: number
          nullable: true
          description: >-
            Total minutes used across all minutes-based companies in the
            selected period. Omitted entirely when no managed company is on the
            minutes billing system.
          example: 1200
        totalCreditsUsed:
          type: number
          nullable: true
          description: >-
            Total credits used across all credits-based companies in the
            selected period. Omitted entirely when no managed company is on the
            credits billing system.
          example: 3000.5
        totalInterviews:
          type: number
          description: Total number of interview usage events across all companies
          example: 80
        breakdownByCostKey:
          description: Global breakdown of usage by cost key across all companies
          type: array
          items:
            $ref: '#/components/schemas/PublicUsageByCostKeyDto'
      required:
        - companies
        - totalInterviews
        - breakdownByCostKey
    PublicCompanyUsageDto:
      type: object
      properties:
        companyId:
          type: string
          description: Company ID
          example: 123e4567-e89b-12d3-a456-426614174000
        companyName:
          type: string
          description: Company name
          example: Acme Corporation
        totalMinutesUsed:
          type: number
          nullable: true
          description: >-
            Total minutes used in the selected period. Present only for
            minutes-based companies; omitted for credits-based companies.
          example: 250
        totalCreditsUsed:
          type: number
          nullable: true
          description: >-
            Total credits used in the selected period. Present only for
            credits-based companies; omitted for minutes-based companies.
          example: 125.5
        billingSystem:
          type: string
          enum:
            - minutes
            - credits
          description: >-
            The billing unit for this company — determines which usage field is
            populated.
          example: credits
        totalInterviews:
          type: number
          description: Total number of interview usage events in the selected period
          example: 12
        breakdownByCostKey:
          description: >-
            Breakdown by logical cost key (currently a single bucket, extensible
            for future products)
          type: array
          items:
            $ref: '#/components/schemas/PublicUsageByCostKeyDto'
      required:
        - companyId
        - companyName
        - billingSystem
        - totalInterviews
        - breakdownByCostKey
    PublicUsageByCostKeyDto:
      type: object
      properties:
        costKey:
          type: string
          description: Logical cost key identifier for the usage bucket
          example: interview_minutes
        minutesUsed:
          type: number
          nullable: true
          description: >-
            Total minutes used for this cost key in the period. Present only for
            minutes-based companies; omitted for credits-based companies.
          example: 120
        creditsUsed:
          type: number
          nullable: true
          description: >-
            Total credits used for this cost key in the period. Present only for
            credits-based companies; omitted for minutes-based companies.
          example: 60.5
        events:
          type: number
          description: >-
            Total number of usage events (transactions/interviews) in this
            bucket
          example: 10
      required:
        - costKey
        - events
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````