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

# Usage History

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

<Note>
  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.
</Note>

## Query

<CodeGroup>
  ```graphql Query theme={null}
  query GetUsageHistory($input: UsageHistoryV2Input!) {
    usageHistoryV2(input: $input) {
      totalUsage
      periods {
        periodStart
        periodEnd
        usage
      }
      markers {
        timestamp
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "customerId": "customer-123",
      "featureId": "feature-api-calls",
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-01-31T23:59:59Z",
      "includeInactiveSubscriptions": true
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "usageHistoryV2": {
        "totalUsage": 45320,
        "periods": [
          {
            "periodStart": "2024-01-01T00:00:00Z",
            "periodEnd": "2024-01-07T23:59:59Z",
            "usage": 10234
          },
          {
            "periodStart": "2024-01-08T00:00:00Z",
            "periodEnd": "2024-01-14T23:59:59Z",
            "usage": 12456
          },
          {
            "periodStart": "2024-01-15T00:00:00Z",
            "periodEnd": "2024-01-21T23:59:59Z",
            "usage": 11230
          },
          {
            "periodStart": "2024-01-22T00:00:00Z",
            "periodEnd": "2024-01-31T23:59:59Z",
            "usage": 11400
          }
        ],
        "markers": [
          {
            "timestamp": "2024-01-15T00:00:00Z"
          }
        ]
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="UsageHistoryV2Input" required>
  Input parameters for usage history query

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      The customer's reference ID
    </ParamField>

    <ParamField body="featureId" type="String" required>
      The feature's reference ID
    </ParamField>

    <ParamField body="startDate" type="DateTime" required>
      Start of the date range
    </ParamField>

    <ParamField body="endDate" type="DateTime" required>
      End of the date range
    </ParamField>

    <ParamField body="includeInactiveSubscriptions" type="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.
    </ParamField>

    <ParamField body="resourceId" type="String">
      Resource ID for multi-resource customers
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

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

<AccordionGroup>
  <Accordion title="Usage analytics dashboard">
    Build usage trend charts showing consumption over time, including for customers who no longer have an active subscription.
  </Accordion>

  <Accordion title="Billing reports">
    Generate usage reports for customer billing visibility.
  </Accordion>

  <Accordion title="Capacity planning">
    Analyze usage patterns to predict future needs.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Example: Build Usage Chart

```javascript theme={null}
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](/api-and-sdks/api-reference/mutations/report-usage) - Report usage