> ## 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.

# Cached usage responses

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.

## Supported endpoints

The currently supported endpoints are:

* [`/v1/subscriptions/<subscription_id>/usage`](/api-reference/subscription/fetch-subscription-usage)
* [`/v1/subscriptions/<subscription_id>/costs`](/api-reference/subscription/fetch-subscription-costs)
* [`/v1/customers/<customer_id>/costs`](/api-reference/customer/fetch-customer-costs)
* [`/v1/customers/external_customer_id/<external_customer_id>/costs`](/api-reference/customer/fetch-customer-costs-by-external-id)
* [`/v1/customers/<customer_id>/credits`](/api-reference/credit/fetch-customer-credit-balance)
* [`/v1/customers/external_customer_id/<external_customer_id>/credits`](/api-reference/credit/fetch-customer-credit-balance-by-external-customer-id)
* [`/v1/customers/<customer_id>/credits/ledger`](/api-reference/credit/fetch-customer-credits-ledger)
* [`/v1/customers/external_customer_id/<external_customer_id>/credits/ledger`](/api-reference/credit/fetch-customer-credits-ledger-by-external-id)
* [`/v1/invoices/upcoming`](/api-reference/invoice/fetch-upcoming-invoice)
* [`/v1/invoices/<invoice_id>`](/api-reference/invoice/fetch-invoice)

<Info>
  Performance benefits are only expected on invoices with `status = "draft"`,
  since issued invoices already have frozen data.
</Info>

## 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)` |

The staleness of the cache is determined based on Orb's invalidation based architecture, which tracks any potentially material changes to an Orb [customer](/core-concepts#customer). Material changes include (but are not limited to) events ingested, subscription lifecycle changes, and prepurchase balance adjustments. Upon receiving an invalidating event, Orb marks a customer as invalid and schedules processing in the near future to rehydrate the cache.

### Response headers

On `HTTP 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`) |

In "always fetch cached" scenarios, we recommend using the `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.