Usage
Usage records track subscription usage for users. This includes data, voice, and text usage. Note that there is a delay in usage data that varies between carriers.
Properties
- Name
- object
- Type
- string
- Description
Type of object is always
usageRecord
.Allowed values:usageRecord
- Name
- data
- Type
- integer
- Description
Amount of data used in bytes.
Example:18883100
- Name
- end
- Type
- string
- Description
Timestamp representing the exclusive upper bound of the aggregation period (e.g. the end of a 24 hour period, subscription period or user-defined set of dates).
Example:"2021-02-15T00:00:00Z"
- Name
- labels
- Type
- object
- Description
- An object containing optional metadata about the usage record.
- Name
- country
- Type
- string
- Description
The ISO 3166-1 alpha-2 country code of the country in which the usage occurred.
Optional: This property may not always be included.Example:"US"
- Name
- subscription
- Type
- string
- Description
The unique identifier for the subscription to which the usage is attributed.
Optional: This property may not always be included.Example:"sub_0SNlurA049MEWV2gSfSxi00xlPIi"
- Name
- sms
- Type
- integer
- Description
Amount of SMS sent and received.
Example:15
- Name
- start
- Type
- string
- Description
Timestamp representing the inclusive lower bound of the aggregation period (e.g. the start of a 24 hour period, subscription period or user-defined set of dates)
Example:"2021-02-14T00:00:00Z"
- Name
- voice
- Type
- integer
- Description
Amount of voice usage in seconds.
Example:240
Example
{
"object": "usageRecord",
"data": 18883100,
"end": "2021-02-15T01:01:01.0Z",
"labels": {
"country": "US",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
},
"sms": 15,
"start": "2021-02-14T01:01:01.0Z",
"voice": 240
}
List subscription usage records
Lists usage records in ascending order for a subscription, defaulting to daily
aggregation for the latest subscription period. If none of the start
, end
, or period
parameters is provided, records are returned for the latest subscription period.
Path Parameters
- Name
- project
- Type
- string
- Description
The unique identifier for the project.
Example:"gigs"
required- Name
- subscription
- Type
- string
- Description
The unique identifier for the subscription.
Example:"sub_0SNlurA049MEWV2gSfSxi00xlPIi"
required
Query Parameters
- Name
- period
- Type
- integer
- Description
Limits the usage data returned to the subscription period provided. This option is incompatible with the
start
andend
parameters.Example:12
>= 1
- Name
- start
- Type
- string
- Description
Limits the usage data to dates greater than or equal to the provided date. Can only be used in combination with
end
.Example:"2021-06-19"
- Name
- end
- Type
- string
- Description
Limits the usage data to dates up to and including the provided date. Can only be used in combination with
start
.Example:"2021-11-14"
- Name
- aggregation
- Type
- string
- Description
Determines the aggregation method used, defaulting to
daily
.period
provides a single aggregated value for the time range or period requested.Allowed values:daily
period
Responses
Returns the list of usage records.
- Name
- object
- Type
- string
- Description
Type of object is always
list
.Allowed values:list
- Name
- items
- Type
- array
- Description
- List of objects of type `usageRecord`.
- Name
- moreItemsAfter
- Type
- nullable string
- Description
A unique identifier to be used as
after
pagination parameter if more items are available sorted after the current batch of items.
- Name
- moreItemsBefore
- Type
- nullable string
- Description
A unique identifier to be used as
before
pagination parameter if more items are available sorted before the current batch of items.
Request
curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/usage \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"
Responses
{
"object": "list",
"items": [
{
"object": "usageRecord",
"data": 18883100,
"end": "2021-02-15T00:00:00Z",
"labels": {
"country": "US",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
},
"sms": 15,
"start": "2021-02-14T00:00:00Z",
"voice": 240
}
],
"moreItemsAfter": null,
"moreItemsBefore": null
}
Simulate subscription usage
Simulates usage on a subscription with a test SIM. Can be used to test usage notifications. Subscription must be in status "active".
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 to share your thoughts.
Body
- Name
- data
- Type
- nullable integer
- Description
Amount of data used in bytes.
Example:18883100
>= 0
- Name
- voice
- Type
- nullable integer
- Description
Amount of voice usage in seconds.
Example:240
>= 0
- Name
- sms
- Type
- nullable integer
- Description
Amount of SMS sent and received.
Example:15
>= 0
- Name
- country
- Type
- nullable string
- Description
The ISO 3166-1 alpha-2 country code to assign to the simulated usage. If not provided, the usage will be assigned to the home country of the provider.
Example:"US"
Path Parameters
- Name
- project
- Type
- string
- Description
The unique identifier for the project.
Example:"gigs"
required- Name
- subscription
- Type
- string
- Description
The unique identifier for the subscription.
Example:"sub_0SNlurA049MEWV2gSfSxi00xlPIi"
required
Responses
Returns the relevant usage record.
- Name
- object
- Type
- string
- Description
Type of object is always
usageRecord
.Allowed values:usageRecord
- Name
- data
- Type
- integer
- Description
Amount of data used in bytes.
Example:18883100
- Name
- end
- Type
- string
- Description
Timestamp representing the exclusive upper bound of the aggregation period (e.g. the end of a 24 hour period, subscription period or user-defined set of dates).
Example:"2021-02-15T00:00:00Z"
- Name
- labels
- Type
- object
- Description
- An object containing optional metadata about the usage record.
- Name
- country
- Type
- string
- Description
The ISO 3166-1 alpha-2 country code of the country in which the usage occurred.
Optional: This property may not always be included.Example:"US"
- Name
- subscription
- Type
- string
- Description
The unique identifier for the subscription to which the usage is attributed.
Optional: This property may not always be included.Example:"sub_0SNlurA049MEWV2gSfSxi00xlPIi"
- Name
- sms
- Type
- integer
- Description
Amount of SMS sent and received.
Example:15
- Name
- start
- Type
- string
- Description
Timestamp representing the inclusive lower bound of the aggregation period (e.g. the start of a 24 hour period, subscription period or user-defined set of dates)
Example:"2021-02-14T00:00:00Z"
- Name
- voice
- Type
- integer
- Description
Amount of voice usage in seconds.
Example:240
Request
curl https://api.gigs.com/testing/projects/{project}/subscriptions/{subscription}/usage \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"data\":18883100,\"voice\":240,\"sms\":15,\"country\":\"US\"}"
Responses
{
"object": "usageRecord",
"data": 18883100,
"end": "2021-02-15T00:00:00Z",
"labels": {
"country": "US",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
},
"sms": 15,
"start": "2021-02-14T00:00:00Z",
"voice": 240
}