The Usage resource
Ability to track records of subscription usage for users. This includes data, voice, and text usage. Note that there is a lag in usage data that varies between carriers.
Properties
- Name
object
- Type
- string
- Description
Type of object is always
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.
Example:US
- Name
subscription
- Type
- string
- Description
The unique identifier for the subscription to which the usage is attributed.
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
Response
{
"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
}
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
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
list
.
required- Name
items
- Type
- array
- Description
- List of objects of type `usageRecord`.
required- 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.
required- 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.
required
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
}