Get Usage Statistics

Get usage statistics for the API key's company

curl --request GET \
  --url https://api.instaview.sk/billing/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.instaview.sk/billing/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instaview.sk/billing/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instaview.sk/billing/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.instaview.sk/billing/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
}

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>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.instaview.sk/billing/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instaview.sk/billing/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instaview.sk/billing/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.instaview.sk/billing/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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: total minutes or credits consumed, the number of conversations, and a breakdown by cost key. Behaviour 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 call-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 call minutes:

{
  "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:

{
  "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.

{
  "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 minutes or credits spent, and how many conversations ran
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 call 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: How many conversations ran. The field keeps its original name — see Resource names — as does the interview_minutes cost key.
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

Show child attributes

totalInterviews

number

required

How many conversations ran across all companies. The field keeps its original name.

Example:

80

breakdownByCostKey

object[]

required

Global breakdown of usage by cost key across all companies

Show child attributes

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

Overview

Agents

Agent Knowledge Base

Jobs

Contacts

Contact Documents

Contact Fields

Companies

Conversations

Runs

Billing

Voice

Webhooks

Sourcing

Phone Numbers

Overview

Date Range Parameters

Regular API Keys (Minutes-Based Company)

Regular API Keys (Credits-Based Company)

ATS Integration Keys

Use Cases

Response Structure

Monitoring Usage

Required Scope

Billing Resource Guide

Scopes & Permissions

ATS Integration

Authorizations

Query Parameters

Response

​Overview

​Date Range Parameters

​Regular API Keys (Minutes-Based Company)

​Regular API Keys (Credits-Based Company)

​ATS Integration Keys

​Use Cases

​Response Structure

​Monitoring Usage

​Required Scope

​Related Resources

Billing Resource Guide

Scopes & Permissions

ATS Integration

Authorizations

Query Parameters

Response

Overview

Date Range Parameters

Regular API Keys (Minutes-Based Company)

Regular API Keys (Credits-Based Company)

ATS Integration Keys

Use Cases

Response Structure

Monitoring Usage

Required Scope

Related Resources