Skip to main content

​
Overview

The Billing API provides read-only access to your usage statistics and interview minutes consumption. Billing is based on interview minutes used, with subscription plans providing included minutes and per-minute pricing for overages.
Required Scope: read:billing is required to access billing and usage endpoints.

​
Usage Endpoint

​
Get Usage Statistics

const response = await fetch(
  'https://api.instaview.sk/billing/usage?start=2024-01-01&end=2024-01-31',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

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

​
Query Parameters

  • start (optional): Start date for the usage period (ISO 8601 format)
  • end (optional): End date for the usage period (ISO 8601 format)
  • If not provided, defaults to the last 30 days

​
Response Structure

{
  "success": true,
  "data": {
    "companies": [
      {
        "companyId": "550e8400-e29b-41d4-a716-446655440000",
        "companyName": "Acme Corp",
        "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
      }
    ]
  },
  "error": null,
  "timestamp": "2024-01-31T10:30:00Z"
}

​
Field Descriptions

  • companies: Array of company-level usage (for ATS keys managing multiple companies, this contains all companies)
  • totalMinutesUsed: Total interview minutes consumed in the period
  • totalInterviews: Total number of interviews conducted
  • breakdownByCostKey: Usage breakdown by cost category (currently only interview_minutes)

​
Subscription Plans

Subscription plans are defined by:
  • maxInterviewMinutes: Interview minutes included in the plan
  • pricePerMonth: Monthly subscription cost
  • pricePerYear: Annual subscription cost (if applicable)
  • pricePerMinute: Per-minute cost for usage beyond included minutes
  • Feature flags: Various boolean flags for features like custom voices, phone numbers, ATS integrations, etc.
Plan details and pricing are managed through your company dashboard. Contact sales for custom plan options.

​
Monitoring Usage

​
Check Remaining Minutes

async function checkUsageStatus() {
  const usage = await getBillingUsage();
  
  const minutesUsed = usage.totalMinutesUsed;
  console.log(`Interview minutes used: ${minutesUsed.toFixed(1)}`);
  console.log(`Total interviews: ${usage.totalInterviews}`);
  
  return usage;
}

​
Usage Alerts

Set up monitoring to track usage patterns: 
async function monitorUsage() {
  const usage = await fetch(
    'https://api.instaview.sk/billing/usage',
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  ).then(r => r.json());
  
  const avgMinutesPerInterview = 
    usage.data.totalMinutesUsed / usage.data.totalInterviews;
  
  console.log(`Average interview length: ${avgMinutesPerInterview.toFixed(1)} minutes`);
  
  // Set up alerts based on your plan limits
  if (usage.data.totalMinutesUsed > 1000) {
    console.warn('High usage detected - consider reviewing subscription plan');
  }
}

​
ATS Integration Keys

For ATS integration keys managing multiple companies, the usage endpoint returns aggregated data across all managed companies: 
{
  "companies": [
    {
      "companyId": "company-a-uuid",
      "companyName": "Company A",
      "totalMinutesUsed": 120.0,
      "totalInterviews": 20
    },
    {
      "companyId": "company-b-uuid",
      "companyName": "Company B",
      "totalMinutesUsed": 125.5,
      "totalInterviews": 22
    }
  ],
  "totalMinutesUsed": 245.5,
  "totalInterviews": 42,
  "breakdownByCostKey": [...]
}

​
Usage Reporting

​
Monthly Usage Report

async function getMonthlyReport(year, month) {
  const start = new Date(year, month - 1, 1).toISOString();
  const end = new Date(year, month, 0, 23, 59, 59).toISOString();
  
  const response = await fetch(
    `https://api.instaview.sk/billing/usage?start=${start}&end=${end}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  
  const { data } = await response.json();
  
  return {
    period: `${year}-${String(month).padStart(2, '0')}`,
    minutes: data.totalMinutesUsed,
    interviews: data.totalInterviews,
    avgMinutesPerInterview: data.totalMinutesUsed / data.totalInterviews
  };
}

// Usage
const report = await getMonthlyReport(2024, 1);
console.log(`January 2024: ${report.minutes} minutes, ${report.interviews} interviews`);

​
Date Range Analysis

async function analyzeUsageTrend(startDate, endDate, intervalDays = 7) {
  const reports = [];
  const current = new Date(startDate);
  const end = new Date(endDate);
  
  while (current <= end) {
    const intervalEnd = new Date(current);
    intervalEnd.setDate(intervalEnd.getDate() + intervalDays);
    
    const response = await fetch(
      `https://api.instaview.sk/billing/usage?start=${current.toISOString()}&end=${intervalEnd.toISOString()}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    
    reports.push({
      start: current.toISOString(),
      end: intervalEnd.toISOString(),
      minutes: data.totalMinutesUsed,
      interviews: data.totalInterviews
    });
    
    current.setDate(current.getDate() + intervalDays);
  }
  
  return reports;
}

​
Cost Breakdown

The breakdownByCostKey field provides granular usage tracking: 
async function getCostBreakdown() {
  const usage = await getBillingUsage();
  
  for (const breakdown of usage.breakdownByCostKey) {
    console.log(`${breakdown.costKey}:`);
    console.log(`  - Minutes: ${breakdown.minutesUsed}`);
    console.log(`  - Events: ${breakdown.events}`);
    console.log(`  - Avg per event: ${(breakdown.minutesUsed / breakdown.events).toFixed(2)} min`);
  }
}

​
Best Practices

Cache usage statistics to reduce API calls:
class UsageCache {
  constructor(ttl = 300000) { // 5 minutes
    this.cache = null;
    this.lastFetch = 0;
    this.ttl = ttl;
  }
  
  async get() {
    if (this.cache && Date.now() - this.lastFetch < this.ttl) {
      return this.cache;
    }
    
    this.cache = await fetchUsageData();
    this.lastFetch = Date.now();
    return this.cache;
  }
}
Monitor usage and set up alerts:
async function checkUsageAlerts(thresholds) {
  const usage = await getBillingUsage();
  
  if (usage.totalMinutesUsed > thresholds.warning) {
    sendAlert('warning', `Usage at ${usage.totalMinutesUsed} minutes`);
  }
  
  if (usage.totalMinutesUsed > thresholds.critical) {
    sendAlert('critical', `Usage exceeded ${thresholds.critical} minutes`);
  }
}
For ATS integrations, monitor usage per company:
async function trackCompanyUsage() {
  const usage = await getBillingUsage();
  
  const sortedCompanies = usage.companies.sort(
    (a, b) => b.totalMinutesUsed - a.totalMinutesUsed
  );
  
  console.log('Top companies by usage:');
  sortedCompanies.slice(0, 10).forEach(company => {
    console.log(`${company.companyName}: ${company.totalMinutesUsed} min`);
  });
}

​
Managing Subscriptions

Subscription changes must be made through the dashboard. The API provides read-only access to usage data. Contact your account manager or visit the billing section of your dashboard to modify your subscription plan.
For subscription changes:
  1. Log in to app.instaview.sk
  2. Navigate to Settings → Billing
  3. View available plans and make changes
  4. Or contact sales: [email protected]

​
Next Steps

Interview API

Schedule and manage interviews

Best Practices

Optimize your API usage

Error Handling

Handle billing errors gracefully

Scopes & Permissions

Understand API key scopes