Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stigg.io/llms.txt

Use this file to discover all available pages before exploring further.

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 GetUsageHistory($input: UsageHistoryV2Input!) {
  usageHistoryV2(input: $input) {
    totalUsage
    periods {
      periodStart
      periodEnd
      usage
    }
    markers {
      timestamp
    }
  }
}

​
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
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

FieldTypeDescription
periodStartDateTimePeriod start time
periodEndDateTimePeriod end time
usageFloatUsage in this period

​
UsageMarker Fields

FieldTypeDescription
timestampDateTimeThe point in time when the subscription’s usage was reset

​
Common Use Cases

Build usage trend charts showing consumption over time, including for customers who no longer have an active subscription.
Generate usage reports for customer billing visibility.
Analyze usage patterns to predict future needs.
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);