Get batched usage data

curl --request POST \
  --url https://api.metronome.com/v1/usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "window_size": "day",
  "starting_on": "2021-01-01T00:00:00Z",
  "ending_before": "2021-01-03T00:00:00Z"
}
'

import requests

url = "https://api.metronome.com/v1/usage"

payload = {
    "window_size": "day",
    "starting_on": "2021-01-01T00:00:00Z",
    "ending_before": "2021-01-03T00:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    window_size: 'day',
    starting_on: '2021-01-01T00:00:00Z',
    ending_before: '2021-01-03T00:00:00Z'
  })
};

fetch('https://api.metronome.com/v1/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.metronome.com/v1/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'window_size' => 'day',
    'starting_on' => '2021-01-01T00:00:00Z',
    'ending_before' => '2021-01-03T00:00:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.metronome.com/v1/usage"

	payload := strings.NewReader("{\n  \"window_size\": \"day\",\n  \"starting_on\": \"2021-01-01T00:00:00Z\",\n  \"ending_before\": \"2021-01-03T00:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.metronome.com/v1/usage")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"window_size\": \"day\",\n  \"starting_on\": \"2021-01-01T00:00:00Z\",\n  \"ending_before\": \"2021-01-03T00:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.metronome.com/v1/usage")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"window_size\": \"day\",\n  \"starting_on\": \"2021-01-01T00:00:00Z\",\n  \"ending_before\": \"2021-01-03T00:00:00Z\"\n}"

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

{
  "data": [
    {
      "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      "billable_metric_id": "9570e4f3-d1da-4b95-ba81-bd40ee002727",
      "billable_metric_name": "CPU hours",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-01-02T00:00:00Z",
      "value": 1234
    },
    {
      "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      "billable_metric_id": "9570e4f3-d1da-4b95-ba81-bd40ee002727",
      "billable_metric_name": "CPU hours",
      "start_timestamp": "2021-01-02T00:00:00Z",
      "end_timestamp": "2021-01-03T00:00:00Z",
      "value": 1234
    }
  ],
  "next_page": null
}

Usage

Get batched usage data

Retrieve aggregated usage data across multiple customers and billable metrics in a single query. This batch endpoint enables you to fetch usage patterns at scale, broken down by time windows, making it ideal for building analytics dashboards, generating reports, and monitoring platform-wide usage trends.

Use this endpoint to:

Generate platform-wide usage reports for internal teams
Monitor aggregate usage trends across your entire customer base
Create comparative usage analyses between customers or time periods
Support capacity planning with historical usage patterns

Key response fields:

An array of UsageBatchAggregate objects containing:

customer_id: The customer this usage belongs to
billable_metric_id and billable_metric_name: What was measured
start_timestamp and end_timestamp: Time window for this data point
value: Aggregated usage amount for the period
groups (optional): Usage broken down by group keys with values
next_page: Pagination cursor for large result sets

Usage guidelines:

Time windows: Set window_size to hour, day, or none (entire period)
Required parameters: Must specify starting_on, ending_before, and window_size
Filtering options:
- customer_ids: Limit to specific customers (omit for all customers)
- billable_metrics: Limit to specific metrics (omit for all metrics)
Pagination: Use next_page cursor to retrieve large datasets
Null values: Group values may be null when no usage matches that group

POST

usage

Get batched usage data

curl --request POST \
  --url https://api.metronome.com/v1/usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "window_size": "day",
  "starting_on": "2021-01-01T00:00:00Z",
  "ending_before": "2021-01-03T00:00:00Z"
}
'

import requests

url = "https://api.metronome.com/v1/usage"

payload = {
    "window_size": "day",
    "starting_on": "2021-01-01T00:00:00Z",
    "ending_before": "2021-01-03T00:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    window_size: 'day',
    starting_on: '2021-01-01T00:00:00Z',
    ending_before: '2021-01-03T00:00:00Z'
  })
};

fetch('https://api.metronome.com/v1/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.metronome.com/v1/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'window_size' => 'day',
    'starting_on' => '2021-01-01T00:00:00Z',
    'ending_before' => '2021-01-03T00:00:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.metronome.com/v1/usage"

	payload := strings.NewReader("{\n  \"window_size\": \"day\",\n  \"starting_on\": \"2021-01-01T00:00:00Z\",\n  \"ending_before\": \"2021-01-03T00:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.metronome.com/v1/usage")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"window_size\": \"day\",\n  \"starting_on\": \"2021-01-01T00:00:00Z\",\n  \"ending_before\": \"2021-01-03T00:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.metronome.com/v1/usage")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"window_size\": \"day\",\n  \"starting_on\": \"2021-01-01T00:00:00Z\",\n  \"ending_before\": \"2021-01-03T00:00:00Z\"\n}"

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

{
  "data": [
    {
      "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      "billable_metric_id": "9570e4f3-d1da-4b95-ba81-bd40ee002727",
      "billable_metric_name": "CPU hours",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-01-02T00:00:00Z",
      "value": 1234
    },
    {
      "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      "billable_metric_id": "9570e4f3-d1da-4b95-ba81-bd40ee002727",
      "billable_metric_name": "CPU hours",
      "start_timestamp": "2021-01-02T00:00:00Z",
      "end_timestamp": "2021-01-03T00:00:00Z",
      "value": 1234
    }
  ],
  "next_page": null
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

next_page

string

Cursor that indicates where the next page of results should start.

Body

application/json

The usage query to run

window_size

enum<string>

required

A window_size of "day" or "hour" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of "none" will return a single usage aggregate for the entirety of the specified period.

Available options:

hour,

day,

none,

HOUR,

DAY,

NONE,

Hour,

Day,

None

starting_on

string<date-time>

required

ending_before

string<date-time>

required

customer_ids

string<uuid>[]

A list of Metronome customer IDs to fetch usage for. If absent, usage for all customers will be returned.

billable_metrics

object[]

A list of billable metrics to fetch usage for. If absent, all billable metrics will be returned.

Show child attributes

Response

200 - application/json

Success

data

object[]

required

Show child attributes

next_page

string | null

required

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

Get batched usage data

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Query Parameters

Body

Response