Skip to main content
GET
/
billing
/
usage
Get usage statistics for the API key's company
curl --request GET \
  --url https://api.instaview.sk/billing/usage \
  --header 'Authorization: Bearer <token>'
{
  "companies": [
    {
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "companyName": "Acme Corporation",
      "billingSystem": "credits",
      "totalInterviews": 12,
      "breakdownByCostKey": [
        {
          "costKey": "interview_minutes",
          "events": 10,
          "minutesUsed": 120,
          "creditsUsed": 60.5
        }
      ],
      "totalMinutesUsed": 250,
      "totalCreditsUsed": 125.5
    }
  ],
  "totalInterviews": 80,
  "breakdownByCostKey": [
    {
      "costKey": "interview_minutes",
      "events": 10,
      "minutesUsed": 120,
      "creditsUsed": 60.5
    }
  ],
  "totalMinutesUsed": 1200,
  "totalCreditsUsed": 3000.5
}
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: 
// 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: 
{
  "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: 
{
  "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. 
{
  "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

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

Required Scope: read:billing is required to access this endpoint. Ensure your API key has this scope enabled.

Billing Resource Guide

Comprehensive guide to billing, usage tracking, and subscription management

Scopes & Permissions

Learn about required scopes

ATS Integration

Understand ATS key usage aggregation

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
start
string

Start of the billing period (inclusive), ISO 8601

Example:

"2025-01-01T00:00:00.000Z"

​
end
string

End of the billing period (exclusive), ISO 8601

Example:

"2025-01-31T00:00:00.000Z"

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

200 - application/json
​
companies
object[]
required

Per-company usage details for all companies visible to this ATS key

​
totalInterviews
number
required

Total number of interview usage events across all companies

Example:

80

​
breakdownByCostKey
object[]
required

Global breakdown of usage by cost key across all companies

​
totalMinutesUsed
number | null

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
number | null

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