Usage

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
PREVIEW
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
}

GET/projects/{project}/subscriptions/{id}/usage

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
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Query Parameters

Name
period
Type
integer
Description
Limits the usage data returned to the subscription period provided. This option is incompatible with the start and end parameters.
Example: 12
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
required
Description
Type of object is always list.
Name
items
Type
array
required
Description
List of objects of type usageRecord.
Name
moreItemsAfter
Type
nullable string
required
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
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/subscriptions/{id}/usage

curl https://api.gigs.com/projects/{project}/subscriptions/{id}/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
}