Orb features several API endpoints to query usage data for a given Subscription or Customer. It’s common to use these in order to power dashboards or views in your own application, allowing your end users to see their current or historical usage. Orb’s data architecture is designed to give you usage results performantly, and the default implementations of usage fetching endpoints prioritize data freshness over latency. When it’s more important to fetch data quickly which may not capture the latest usage, Orb provides the ability for you to query cached results. By default, Orb does not recompute data when it’s known to be fresh, and also provides an explicit opt-in feature to use cached and potentially stale data. We recommend using this in cases where you plan to render a chart or preview on page load, allowing you to build an interaction where the latest data is loaded asynchronously if necessary. The performance difference between fetching cached and live data depends on the number and cost of queries against the events datastore that would otherwise be required. In most cases, you should expect at a 1.5-2x speedup in latency.Documentation Index
Fetch the complete documentation index at: https://docs.withorb.com/llms.txt
Use this file to discover all available pages before exploring further.
Supported endpoints
The currently supported endpoints are:/v1/subscriptions/<subscription_id>/usage/v1/subscriptions/<subscription_id>/costs/v1/customers/<customer_id>/costs/v1/customers/external_customer_id/<external_customer_id>/costs/v1/invoices/upcoming/v1/invoices/<invoice_id>
Performance benefits are only expected on invoices with
status = "draft",
since issued invoices already have frozen data.Header semantics
Orb currently supports two approaches for requesting cached data.Always fetching cached data
In order to opt-in to cached data, explicitly pass the following case-sensitive header:| Key | Value |
|---|---|
Orb-Cache-Control | cache |
Fetch cached data conditional on a staleness threshold
In order to conditionally opt-in to cached data based on a maximum staleness age, pass the following headers:| Key | Value |
|---|---|
Orb-Cache-Control | cache |
Orb-Cache-Max-Age-Seconds | <staleness_threshold_seconds> (int) |
Response headers
OnHTTP 200 responses when the Orb-Cache-Control header is passed with or without Orb-Cache-Max-Age-Seconds, the response will return the following
header:
| Key | Value |
|---|---|
Orb-Cache-Updated-At | ISO timestamp string (e.g. 2024-02-14T06:48:26.366184+00:00) |
Orb-Cache-Updated-At value to determine if a follow-up request is necessary. If a specific result is completely up to date (based on internal event ingestion invalidation markers), Orb will set this value to the current time.