Usage History

Retrieves historical usage data for a customer’s metered feature.

Usage history can now be retrieved regardless of whether the customer currently has an active subscription. Pass includeInactiveSubscriptions: true when using the GraphQL API or GraphQL-based SDKs. The REST API supports this automatically — no extra parameter needed.

Query

Query

query GetUsageHistory($input: UsageHistoryV2Input!) {
  usageHistoryV2(input: $input) {
    totalUsage
    periods {
      periodStart
      periodEnd
      usage
    }
    markers {
      timestamp
    }
  }
}

Parameters

input · UsageHistoryV2Input · required

Input parameters for usage history query

Show properties

customerId · String · required

The customer’s reference ID

featureId · String · required

The feature’s reference ID

startDate · DateTime · required

Start of the date range

endDate · DateTime · required

End of the date range

includeInactiveSubscriptions · Boolean

When true, returns usage history even if the customer has no active subscription or had no subscription during the requested time frame. If the customer does have an active subscription, the response also includes a markers array with the subscription’s usage reset periods.

GraphQL API and GraphQL-based SDKs only. The REST API supports this behavior automatically.

resourceId · String

Resource ID for multi-resource customers

environmentId · UUID

Environment ID

Return Type

Returns a UsageHistoryV2 object with:

Field	Type	Description
totalUsage	Float	Total usage in the period
periods	[UsagePeriod]	Usage broken down by period
markers	[UsageMarker]	Subscription usage reset timestamps. Only present when the customer has an active subscription. Use these to cross-reference raw usage data with entitlement reset boundaries.

UsagePeriod Fields

Field	Type	Description
periodStart	DateTime	Period start time
periodEnd	DateTime	Period end time
usage	Float	Usage in this period

UsageMarker Fields

Field	Type	Description
timestamp	DateTime	The point in time when the subscription’s usage was reset

Common Use Cases

Usage analytics dashboard

Build usage trend charts showing consumption over time, including for customers who no longer have an active subscription.

Billing reports

Generate usage reports for customer billing visibility.

Capacity planning

Analyze usage patterns to predict future needs.

Cross-referencing usage with entitlement resets

Use the markers array to overlay subscription usage reset boundaries onto raw usage charts, making it easy to see exactly how much was consumed within each billing period.

Example: Build Usage Chart

const { data } = await client.query({
  query: GET_USAGE_HISTORY,
  variables: {
    input: {
      customerId: user.customerId,
      featureId: "feature-api-calls",
      startDate: thirtyDaysAgo,
      endDate: today,
      includeInactiveSubscriptions: true
    }
  }
});

const chartData = data.usageHistoryV2.periods.map(p => ({
  date: new Date(p.periodStart).toLocaleDateString(),
  usage: p.usage
}));

const resetMarkers = data.usageHistoryV2.markers?.map(m => m.timestamp) ?? [];

renderUsageChart(chartData, resetMarkers);

Related Operations

• Report Usage - Report usage