# Introduction to Usage

Usage at Gigs represents usage records reported to Gigs by mobile carriers, that reflects data, voice, and SMS consumption by users. This data provides the latest available traffic measurements; records arrive with a delay after the activity occurs. The [Usage API][usage-apis] allow you to show usage to your users as well as aggregate data for reporting purposes.

## What Usage Enables

<Note type="info">

Usage at Gigs reports volume (bytes, seconds, or messages), timing, and roaming country. It does not include application-level detail such as which apps or websites were accessed, message content, or precise location.

</Note>

| Capability | What it enables | API Example |
| --- | --- | --- |
| Subscription usage balances | "You've used 3.2GB of your 5GB plan" - with used, remaining, and percentage | [Current Plan Balance][usage-api-current-balance] |
| Per-country breakdown | "800MB in Spain, 1.2GB in France" - essential for travel products | [Aggregate by Country][usage-api-country] |
| Per-add-on tracking | Each top-up or add-on has its own balance - "Travel pack: 1.1GB / 2GB" | [Fetch add-on balances][usage-api-addons]|
| Threshold notifications | Automated alerts at usage intervals - 50% through 100% | [See Usage Events][usage-events] |

## Next Steps

- [Usage APIs][usage-apis] - Common Usage API requests.
- [Usage Balances Core Concepts][usage-balances-core-concepts] - Covers the core concepts of the Usage Balances object model.
- [Usage Records Core Concepts][usage-records-core-concepts] - Covers the usageRecord object, aggregation modes, filtering and labels.
- [Usage Events][usage-events] - Subscribe to webhook events for usage thresholds, first-use detection and data throttling.
- [Testing Usage Balances][usage-balances-testing] - How to test and simulate usage on Usage Balances
- [Creating Subscriptions][subscription] - Learn how to create subscriptions with the Gigs API.
- [Add-ons][addons-guide] - Learn how purchased add-ons generate their own usage balances.

[usage-balances-core-concepts]: /docs/core/usage/usage-balances-core-concepts
[usage-records-core-concepts]: /docs/core/usage/usage-records-core-concepts
[usage-events]: /docs/core/usage/usage-events
[usage-apis]: /docs/core/usage/apis-for-usage
[usage-api-current-balance]: /docs/core/usage/apis-for-usage#get-current-period-plan-balances-for-a-subscription
[usage-api-country]: /docs/core/usage/apis-for-usage#aggregate-by-country
[usage-api-addons]: /docs/core/usage/apis-for-usage#fetch-add-on-balances-by-add-on-id
[usage-balances-testing]: /docs/core/usage/testing-usage-balances
[usage-api]: /api/latest/core/usage
[usage-balances-api]: /api/latest/core/usage-balances
[subscription]: /docs/create-a-subscription
[addons-guide]: /docs/core/add-ons