Query Meter Usage

curl --request GET \
  --url https://api.paygentic.io/v0/billableMetrics/{id}/meter \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.paygentic.io/v0/billableMetrics/{id}/meter', 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.paygentic.io/v0/billableMetrics/{id}/meter",
  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.paygentic.io/v0/billableMetrics/{id}/meter"

	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.paygentic.io/v0/billableMetrics/{id}/meter")

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

{
  "object": "meter",
  "billableMetricId": "bm_abc",
  "totalValue": 42.5,
  "windowedValues": [
    {
      "windowStart": "2025-06-15T10:00:00.000Z",
      "windowEnd": "2025-06-15T11:00:00.000Z",
      "value": 12
    }
  ],
  "groupedValues": [
    {
      "groupBy": {
        "model": "gpt-4"
      },
      "value": 30,
      "eventCount": 3
    }
  ]
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

GET

billableMetrics

{id}

meter

Query Meter Usage

curl --request GET \
  --url https://api.paygentic.io/v0/billableMetrics/{id}/meter \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.paygentic.io/v0/billableMetrics/{id}/meter', 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.paygentic.io/v0/billableMetrics/{id}/meter",
  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.paygentic.io/v0/billableMetrics/{id}/meter"

	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.paygentic.io/v0/billableMetrics/{id}/meter")

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

{
  "object": "meter",
  "billableMetricId": "bm_abc",
  "totalValue": 42.5,
  "windowedValues": [
    {
      "windowStart": "2025-06-15T10:00:00.000Z",
      "windowEnd": "2025-06-15T11:00:00.000Z",
      "value": 12
    }
  ],
  "groupedValues": [
    {
      "groupBy": {
        "model": "gpt-4"
      },
      "value": 30,
      "eventCount": 3
    }
  ]
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

Authorizations

Authorization

string

header

required

API key authentication

Path Parameters

string

required

Unique identifier for a billable metric

Pattern: ^bm_[a-zA-Z0-9]+$

Query Parameters

from

string<date-time>

required

Start of query window (ISO 8601)

string<date-time>

required

End of query window (ISO 8601)

subject

string

Filter by customer/user ID

windowSize

enum<string>

Time bucket granularity

Available options:

MINUTE,

HOUR,

DAY,

MONTH

filterGroupBy

string

JSON-encoded dimension filter (e.g. {"key":"value"})

groupBy

string

Comma-separated dimension keys. Configure keys for the grouping on the metric. Only the "subject" grouping is supported by default.

groupLimit

integer

Cap groupedValues to the top-N by value (descending). With windowSize, restricts the windowed series to those top-N groups. Bounds the payload for high-cardinality groupings; groupCount reports the untruncated distinct-group count.

Required range: 1 <= x <= 500

groupOffset

integer

Offset into the value-descending group ordering; requires groupLimit to page through grouped results. With windowSize set, pages the windowed series through the ranked groups (offset 0 yields the top-N).

Required range: 0 <= x <= 100000

Response

Usage data

object

enum<string>

default:meter

required

Available options:

meter

billableMetricId

string

required

Unique identifier for a billable metric

Pattern: ^bm_[a-zA-Z0-9]+$

totalValue

number

required

Total aggregated value across the query window

windowedValues

object[]

Time-bucketed values. Only present when windowSize is specified. When both windowSize and groupBy are set, windowedValues[i] is index-aligned with groupedValues[i] (same window and group).

Show child attributes

groupedValues

object[]

Dimension-grouped values. Only present when groupBy is specified. When both windowSize and groupBy are set, groupedValues[i] is index-aligned with windowedValues[i] (same window and group).

Show child attributes

groupCount

integer

Total distinct groups before groupLimit/groupOffset truncation. Only present when groupLimit is specified; use it to drive pagination totals.

Billable Metrics

Customers

Entitlements

Grants

Features

Fees

Plans

Prices

Products

Sources

Subscriptions

Users

Invoices V2

Payments

Payment Sessions

Events

Costs

Revenue

Profitability

Test Clocks

ExternalReferences

Items

Orders

Billing Schedules

Salesforce

MerchantIntegrations

Approvals

Query Meter Usage

Authorizations

Path Parameters

Query Parameters

Response