Usage API

What was streamed in a month and what it cost, stream by stream, and per customer — what a partner bills its own customers from.

This page is generated from the OpenAPI specification; the same text is inMarkdown for tools and AI assistants.

Read a month's usage

GET/v1/usage

What was streamed in a month (UTC) and what it cost, broken down stream by stream. With customer_ref, one customer’s — what a partner bills that customer from.

Query parameters

Name	Type	Description
month	string	`YYYY-MM`. Defaults to the current month (UTC).
customer_ref	string	Only this customer’s usage.

Response 200

The month’s usage.

Fields

Name	Type	Description
monthrequired	string	`YYYY-MM`.
customer_ref	string	Your identifier for a customer. 1-128 letters, digits, `.`, `_` or `-`; not `.` or `..`.
stream_hours_usedrequired	number
restream_destination_hours_usedrequired	number
captions_hours_used	number
translation_language_hours_used	number
stream_hour_caprequired	number or null	Your organization’s monthly cap, or null for none.
stream_hours_remainingrequired	number or null
streamsrequired	array of object
streams[].playback_idrequired	string
streams[].customer_refrequired	string	Your identifier for a customer. 1-128 letters, digits, `.`, `_` or `-`; not `.` or `..`.
streams[].titlerequired	string
streams[].tierrequired	string	`standard_1080p` ($5 per stream-hour) or `pro_4k` ($20 per stream-hour). One of `"standard_1080p"`, `"pro_4k"`.
streams[].billable_minutesrequired	integer
streams[].unit_rate_usd_per_hourrequired	number
streams[].amount_usdrequired	number
streams[].occurred_atrequired	string (date-time)
streams[].restream_billable_minutesrequired	integer
streams[].restream_destinationsrequired	integer
streams[].restream_unit_rate_usd_per_hourrequired	number or null
streams[].restream_amount_usdrequired	number
streams[].restream_destination_minutesrequired	array of integer
streams[].end_reasonrequired	string or null
streams[].started_atrequired	string (date-time) or null
streams[].captions	object
streams[].captions.captions_billable_minutesrequired	integer
streams[].captions.captions_amount_usdrequired	number
streams[].captions.translationsrequired	array of object
streams[].captions.translations[].languagerequired	string
streams[].captions.translations[].namerequired	string
streams[].captions.translations[].billable_minutesrequired	integer
streams[].captions.translations[].unit_rate_usd_per_hourrequired	number
streams[].captions.translations[].amount_usdrequired	number
streams[].captions.translation_billable_minutesrequired	integer
streams[].captions.translation_amount_usdrequired	number

Errors

Status	Code	Meaning
400	invalid_month	`month` is not `YYYY-MM`.
400	invalid_customer_ref	`customer_ref` is not a valid customer reference.

curl "https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/usage",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    params={
        "month": "2026-09",
        "customer_ref": "grace-chapel",
    },
    timeout=30,
)
print(response.status_code, response.text)

const response = await fetch('https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);

const response: Response = await fetch('https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/usage', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'query' => [
        'month' => '2026-09',
        'customer_ref' => 'grace-chapel',
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;

require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body

package main

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

func main() {
  req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/usage?month=2026-09&customer_ref=grace-chapel");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Read usage month by month

GET/v1/usage/months

One entry per calendar month (UTC), oldest first, with zero months included: broadcasts, billed stream minutes by tier, every priced line and the total in cents — the amounts the month’s invoice uses. The current month is the invoice so far (broadcasts that have ended).

Query parameters

Name	Type	Description
from	string	First month, `YYYY-MM`. Defaults to eleven months before `to`.
to	string	Last month, `YYYY-MM`, inclusive. Defaults to the current month. At most 36 months from `from`.
customer_ref	string	Only this customer’s usage.

Response 200

Usage by month.

Fields

Name	Type	Description
fromrequired	string
torequired	string
customer_ref	string	Echoed when the request named one.
monthsrequired	array of object
months[].monthrequired	string	`YYYY-MM` (UTC).
months[].streamsrequired	integer	Broadcasts that ended (and were billed) in the month.
months[].stream_minutesrequired	object	Billed stream minutes by tier; both tiers are always present.
months[].stream_minutes.standard_1080prequired	integer
months[].stream_minutes.pro_4krequired	integer
months[].linesrequired	array of object
months[].lines[].productrequired	string	One of `"stream"`, `"restream"`, `"captions"`, `"translation"`.
months[].lines[].tierrequired	string	One of `"standard_1080p"`, `"pro_4k"`.
months[].lines[].minutesrequired	integer	Billed minutes.
months[].lines[].centsrequired	integer	The amount in whole cents, exactly as invoiced.
months[].usage_centsrequired	integer

Errors

Status	Code	Meaning
400	invalid_month	`from` or `to` is not `YYYY-MM`.
400	invalid_range	`from` is after `to`, or the range is longer than 36 months.
400	invalid_customer_ref	`customer_ref` is not a valid customer reference.

curl "https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/usage/months",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    params={
        "from": "2026-04",
        "to": "2026-09",
    },
    timeout=30,
)
print(response.status_code, response.text)

const response = await fetch('https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);

const response: Response = await fetch('https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/usage/months', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'query' => [
        'from' => '2026-04',
        'to' => '2026-09',
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;

require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body

package main

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

func main() {
  req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/usage/months?from=2026-04&to=2026-09");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Read a month's usage by customer

GET/v1/usage/customers

One month’s usage per customer, highest spend first, with the name you gave each. Only customers that streamed that month appear.

Query parameters

Name	Type	Description
month	string	`YYYY-MM`. Defaults to the current month (UTC).

Response 200

Usage by customer.

Fields

Name	Type	Description
monthrequired	string
customersrequired	array of object
customers[].customer_refrequired	string
customers[].namerequired	string or null
customers[].streamsrequired	integer
customers[].stream_minutesrequired	object	Billed stream minutes by tier; both tiers are always present.
customers[].stream_minutes.standard_1080prequired	integer
customers[].stream_minutes.pro_4krequired	integer
customers[].linesrequired	array of object
customers[].lines[].productrequired	string	One of `"stream"`, `"restream"`, `"captions"`, `"translation"`.
customers[].lines[].tierrequired	string	One of `"standard_1080p"`, `"pro_4k"`.
customers[].lines[].minutesrequired	integer	Billed minutes.
customers[].lines[].centsrequired	integer	The amount in whole cents, exactly as invoiced.
customers[].usage_centsrequired	integer

Errors

Status	Code	Meaning
400	invalid_month	`month` is not `YYYY-MM`.

curl "https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/usage/customers",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    params={
        "month": "2026-09",
    },
    timeout=30,
)
print(response.status_code, response.text)

const response = await fetch('https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);

const response: Response = await fetch('https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/usage/customers', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'query' => [
        'month' => '2026-09',
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;

require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body

package main

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

func main() {
  req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/usage/customers?month=2026-09");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");