Skip to main content
Retrieves historical usage data for a customer’s metered feature.

​
Query

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

​
Parameters

​
input
UsageHistoryV2Input
required
Input parameters for usage history query

​
Return Type

Returns a UsageHistoryV2 object with:
FieldTypeDescription
totalUsageFloatTotal usage in the period
periods[UsagePeriod]Usage broken down by period

​
UsagePeriod Fields

FieldTypeDescription
periodStartDateTimePeriod start time
periodEndDateTimePeriod end time
usageFloatUsage in this period

​
Common Use Cases

Build usage trend charts showing consumption over time.
Generate usage reports for customer billing visibility.
Analyze usage patterns to predict future needs.

​
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
    }
  }
});

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

renderUsageChart(chartData);