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",
      "totalMinutesUsed": 250,
      "totalInterviews": 12,
      "breakdownByCostKey": [
        {
          "costKey": "interview_minutes",
          "minutesUsed": 120,
          "events": 10
        }
      ]
    }
  ],
  "totalMinutesUsed": 1200,
  "totalInterviews": 80,
  "breakdownByCostKey": [
    {
      "costKey": "interview_minutes",
      "minutesUsed": 120,
      "events": 10
    }
  ]
}
Retrieves usage statistics for the API key’s company, including total minutes used, interview counts, and breakdown by cost key. Behavior differs between regular API keys and ATS integration keys.

​
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.

​
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

For regular API keys, the response includes usage for the single associated company: 
{
  "data": {
    "companies": [
      {
        "companyId": "company-uuid",
        "companyName": "Your Company",
        "totalMinutesUsed": 245.5,
        "totalInterviews": 42
      }
    ],
    "totalMinutesUsed": 245.5,
    "totalInterviews": 42,
    "breakdownByCostKey": {
      "standard": 200.0,
      "premium": 45.5
    }
  }
}

​
ATS Integration Keys

For ATS keys, the response includes aggregated usage across all managed companies: 
{
  "data": {
    "companies": [
      {
        "companyId": "company-a-uuid",
        "companyName": "Client Company A",
        "totalMinutesUsed": 120.0,
        "totalInterviews": 20
      },
      {
        "companyId": "company-b-uuid",
        "companyName": "Client Company B",
        "totalMinutesUsed": 125.5,
        "totalInterviews": 22
      }
    ],
    "totalMinutesUsed": 245.5,
    "totalInterviews": 42
  }
}

​
Use Cases

  • Usage Monitoring: Track interview minutes 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)
  • totalMinutesUsed: Total interview minutes consumed in the period
  • totalInterviews: Total number of interviews conducted
  • breakdownByCostKey: Usage breakdown by cost category

​
Monitoring Usage

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

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

  console.log(`Total minutes used: ${data.totalMinutesUsed}`);
  console.log(`Total interviews: ${data.totalInterviews}`);

  // For ATS keys, check per-company usage
  if (data.companies.length > 1) {
    data.companies.forEach((company) => {
      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"

Response

200 - application/json
​
companies
object[]
required

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

​
totalMinutesUsed
number
required

Total minutes used across all companies in the selected period

Example:

1200

​
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