# Usage Balances

## The UsageBalance object

A usage balance represents the amount of usage consumed from an [Allowance](https://developers.gigs.com/core/schemas/allowance) for a given [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) in a certain Period.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `usageBalance`. |
| `id` | string | Yes | Unique identifier for the usage balance. |
| `allowance` | object | Yes | The [Allowance](https://developers.gigs.com/core/schemas/allowance) this usage balance is tracking. |
| `subscription` | string | Yes | Unique identifier of the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) the usage balance is related to. |
| `source` | object | Yes | The entity providing the allowance to the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource). |
| `unit` | bytes | seconds | messages | Yes | The unit the usage is counted in. |
| `used` | integer | Yes | The amount of usage consumed, counted in `unit`. |
| `limit` | integer,null | Yes | The amount of usage permitted by the associated allowance counted in `unit`. A value of `null` indicates an unlimited allowance. |
| `remaining` | integer,null | Yes | The amount remaining that can still be consumed, counted in `unit`. A value of `null` indicates an unlimited allowance. |
| `usedPercent` | integer,null | Yes | The percentage of `limit` that has been used, expressed as an integer between 0 and 100. A value of `null` indicates an unlimited allowance. |
| `remainingPercent` | integer,null | Yes | The percentage of `limit` that has not been used, expressed as an integer between 0 and 100. A value of `null` indicates an unlimited allowance. |
| `usableFrom` | string,null | Yes | Timestamp representing the beginning of this usage balance's validity. A value of `null` indicates a Balance that is not yet active, for example when a Subscription is still pending. |
| `usableUntil` | string,null | Yes | Timestamp representing the end of this usage balance's validity. A value of `null` indicates a Balance that is not yet active, for example when a Subscription is still pending. |

---

## List all usage balances

`GET /projects/{project}/usageBalances`

Returns a list of usage balances for the given project. The list can be filtered by subscription, subscription period, or subscription add-on. When filtering by subscription without specifying subscriptionPeriod or subscriptionAddon, all usage balances for the subscription are returned regardless of source type or period.

> **Info**
> #### Preview
> 
>  This endpoint is currently in preview and might change in the future.
> 
>  We’re excited to hear your feedback and ideas. Please send an email
>  to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription` | string | No | Filter usage balances by [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) ID. |
| `subscriptionPeriod` | string | No | Filter usage balances by subscription period. Requires the `subscription` parameter. Accepts a positive integer, the special value `current`, or a negative integer to request previous periods (e.g., `-1` for the previous period). Cannot be combined with `subscriptionAddon`. A usage balance is sourced from either a subscription period or a subscription add-on, never both - combining these will return an error. |
| `subscriptionAddon` | string | No | Filter usage balances by [Subscription Add-on](https://developers.gigs.com/core/subscription-add-ons#the-subscription-add-on-resource) ID. Can be combined with `subscription` but not with `subscriptionPeriod`. A usage balance is sourced from either a subscription period or a subscription add-on, never both — combining these will return an error. |
| `after` | string | No | A cursor for use in pagination. The `after` parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned. |
| `before` | string | No | A cursor for use in pagination. The `before` parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned. |
| `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. |

### Responses

#### 200 — Returns a list of usage balances.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `usageBalance`. |
| `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. |
| `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Retrieve a usage balance

`GET /projects/{project}/usageBalances/{usageBalance}`

Returns the details of an existing usage balance.

> **Info**
> #### Preview
> 
>  This endpoint is currently in preview and might change in the future.
> 
>  We’re excited to hear your feedback and ideas. Please send an email
>  to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `usageBalance` | string | Yes | The unique identifier for the usage balance. |

### Responses

#### 200 — Returns the usage balance.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `usageBalance`. |
| `id` | string | Yes | Unique identifier for the usage balance. |
| `allowance` | object | Yes | The [Allowance](https://developers.gigs.com/core/schemas/allowance) this usage balance is tracking. |
| `subscription` | string | Yes | Unique identifier of the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) the usage balance is related to. |
| `source` | object | Yes | The entity providing the allowance to the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource). |
| `unit` | bytes | seconds | messages | Yes | The unit the usage is counted in. |
| `used` | integer | Yes | The amount of usage consumed, counted in `unit`. |
| `limit` | integer,null | Yes | The amount of usage permitted by the associated allowance counted in `unit`. A value of `null` indicates an unlimited allowance. |
| `remaining` | integer,null | Yes | The amount remaining that can still be consumed, counted in `unit`. A value of `null` indicates an unlimited allowance. |
| `usedPercent` | integer,null | Yes | The percentage of `limit` that has been used, expressed as an integer between 0 and 100. A value of `null` indicates an unlimited allowance. |
| `remainingPercent` | integer,null | Yes | The percentage of `limit` that has not been used, expressed as an integer between 0 and 100. A value of `null` indicates an unlimited allowance. |
| `usableFrom` | string,null | Yes | Timestamp representing the beginning of this usage balance's validity. A value of `null` indicates a Balance that is not yet active, for example when a Subscription is still pending. |
| `usableUntil` | string,null | Yes | Timestamp representing the end of this usage balance's validity. A value of `null` indicates a Balance that is not yet active, for example when a Subscription is still pending. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---