GET /api/v1/usage

Paginated usage history: each row is one billed event (async settlement or synchronous endpoint charge). Read-only; scoped to the authenticated user.

Query parameters

Param	Default	Notes
page	1	1-based page index.
limit	50	Page size, 1–200. Invalid → 400.
sort	id	One of: id, created_at, eur_cents_charged, credits_charged, units.
order	desc	asc or desc.

Call the endpoint

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  "https://api.sybilion.dev/api/v1/usage?page=1&limit=20&sort=created_at&order=desc"

Python

total = 0
for page in client.iter_usage_pages(limit=50):
    total += len(page.usage_events)
print("usage events:", total)

Go

err := c.ForEachUsagePage(context.Background(), "created_at", "desc", 50,
	func(ctx context.Context, page *api.ApiV1UsageGet200Response) (bool, error) {
		fmt.Println("page total:", page.Pagination.GetTotal())
		return false, nil
	},
)
if err != nil {
	log.Fatal(err)
}

R

library(sybilion)

cl <- sybilion_client(token = Sys.getenv("SYBILION_API_TOKEN"))
total <- 0
cl$iter_usage_pages(function(page) {
  total <<- total + length(page$usage_events)
})
cat("usage events:", total, "\n")

Java

import com.sybilion.Client;
import com.sybilion.Options;

Client c = new Client(Options.builder().token(System.getenv("SYBILION_API_TOKEN")).build());
final int[] total = {0};
c.forEachUsagePage("created_at", "desc", 50, page -> {
    total[0] += page.getUsageEvents().size();
    System.out.println("page total: " + page.getPagination().getTotal());
    return false; // only first page
});

Response

{
  "usage_events": [
    {
      "id": 4821,
      "endpoint": "forecast",
      "units": 1,
      "credits_charged": 3,
      "eur_cents_charged": 3,
      "created_at": "2026-04-30T10:05:42Z",
      "async_job_id": "1f2a8b3e-4c5d-46d7-9a01-2b3c4d5e6f70"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "total_pages": 8,
    "sort": "created_at",
    "order": "desc"
  }
}

Field reference

usage_events[]

Field	Meaning
id	Auto-increment row identifier.
endpoint	Billing route key (e.g. "forecast", "drivers", "alerts"). May be null on older rows.
units	Metered quantity — item count for per-result billing, or 1 for flat-fee calls.
credits_charged	Whole credits debited.
eur_cents_charged	EUR cents debited.
created_at	ISO 8601 timestamp of when the charge was recorded.
async_job_id	UUID of the related async job, or null for synchronous calls.

pagination

Field	Meaning
page	Current 1-indexed page.
limit	Page size used for this response.
total	Total matching rows across all pages.
total_pages	ceil(total / limit).
sort	Sort field used.
order	Sort direction used.

Common errors

Code	Cause	What to do
400	Invalid query parameter (e.g. limit out of range, unrecognised sort).	Check the query parameters table above.
401	Missing or invalid bearer token.	Check the API key.