List Usage Events

GET

usage

events

List recent raw usage events

curl --request GET \
  --url https://billing.example.com/v1/usage/events \
  --header 'Authorization: Bearer <token>'

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

fetch('https://billing.example.com/v1/usage/events', 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://billing.example.com/v1/usage/events",
  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://billing.example.com/v1/usage/events"

	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://billing.example.com/v1/usage/events")

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

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dimension": "<string>",
      "quantity": 123,
      "timestamp": "2023-11-07T05:31:56Z",
      "properties": {},
      "transaction_id": "<string>"
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Returns the raw events your services reported through Record Usage Event and Record Usage Events (Batch), newest first. This is the “did my events actually land?” view for debugging metering — it is not aggregated. For billing-shaped numbers use Query Usage (time buckets) or Get Subscription Usage (current-period totals with entitlement headroom). The stream is tenant-scoped through the subscription: only events on subscriptions that belong to the authenticated tenant are returned.

Query Parameters

Parameter	Type	Required	Description
`customer_id`	string (UUID)	No	Only events for this customer
`dimension`	string	No	Only events for this dimension (exact match, e.g. `api_calls`)
`limit`	integer	No	Page size. Default `50`, capped at `200`
`offset`	integer	No	Rows to skip. Default `0`

Example Request

curl "https://api.recurso.dev/v1/usage/events?customer_id=d5b7c1de-8a34-4a37-8f0e-b1a9f3f6f001&dimension=api_calls&limit=2" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "7c1de5b7-1f6d-4a37-8f0e-b1a9f3f6f002",
      "subscription_id": "9a1f0f9e-52f1-4c11-a1b0-1f6d3f1c2a7e",
      "customer_id": "d5b7c1de-8a34-4a37-8f0e-b1a9f3f6f001",
      "dimension": "api_calls",
      "quantity": 150,
      "timestamp": "2026-07-06T23:58:01Z",
      "properties": { "region": "ap-south-1" },
      "transaction_id": "req_01J1Z8K3Q4"
    },
    {
      "id": "3f9a2b7c-8d1e-4f60-a5b4-c2d3e4f5a603",
      "subscription_id": "9a1f0f9e-52f1-4c11-a1b0-1f6d3f1c2a7e",
      "customer_id": "d5b7c1de-8a34-4a37-8f0e-b1a9f3f6f001",
      "dimension": "api_calls",
      "quantity": 42,
      "timestamp": "2026-07-06T23:57:12Z"
    }
  ]
}

Fields

Field	Type	Description
`id`	string (UUID)	Event ID (the `event_id` returned at ingestion)
`subscription_id`	string (UUID)	Subscription the usage was recorded against
`customer_id`	string (UUID)	The subscription’s customer
`dimension`	string	Usage dimension / meter name
`quantity`	integer	Quantity recorded on the event
`timestamp`	string (RFC 3339)	Ingestion time, set server-side
`properties`	object	Free-form string attributes sent with the event; omitted when none
`transaction_id`	string	Caller-supplied idempotency key; omitted when none was sent

The list is ordered by timestamp descending and carries no has_more flag — page with offset until a page comes back shorter than limit.

Errors

Status	Code	When	Fix
`400`	`validation_failed`	`customer_id` is not a valid UUID	Pass the customer’s UUID, or drop the filter
`401`	`unauthorized`	Missing or invalid API key / session	Send `Authorization: Bearer $API_KEY`
`500`	`internal_error`	Reading the event stream failed	Retry; contact support if it persists

Errors use the standard envelope — see Errors.

Non-numeric or negative limit / offset values are not rejected: limit falls back to the default of 50 (and anything above 200 is clamped to 200), and a negative offset is treated as 0.

Authorizations

Authorization

string

header

required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Query Parameters

customer_id

string<uuid>

dimension

string

limit

integer

default:50

Required range: x <= 200

offset

integer

default:0

Response

Raw usage events, newest first.

data

object[]

Show child attributes

List recent raw usage events

curl --request GET \
  --url https://billing.example.com/v1/usage/events \
  --header 'Authorization: Bearer <token>'

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

fetch('https://billing.example.com/v1/usage/events', 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://billing.example.com/v1/usage/events",
  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://billing.example.com/v1/usage/events"

	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://billing.example.com/v1/usage/events")

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

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dimension": "<string>",
      "quantity": 123,
      "timestamp": "2023-11-07T05:31:56Z",
      "properties": {},
      "transaction_id": "<string>"
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Query Parameters

Example Request

Response

Fields

Errors

Authorizations

Query Parameters

Response

​Query Parameters

​Example Request

​Response

​Fields

​Errors

Authorizations

Query Parameters

Response

Query Parameters

Example Request

Response

Fields

Errors