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
dataDeviceBytes
Type
integer
Status
PREVIEW
Description
Amount of on-device data used in bytes.
Optional: This property may not always be included.
Example: 30029300
Name
dataTetheringBytes
Type
integer
Status
PREVIEW
Description
Amount of tethering data used in bytes.
Optional: This property may not always be included.
Example: 30029300
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
roaming
Type
string
Status
PREVIEW
Description
The roaming mode the usage occurred in.
Optional: This property may not always be included.
Allowed values: none international domestic
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 messages sent and received.
Example: 15
Name
smsInternationalMessages
Type
integer
Status
PREVIEW
Description
Amount of SMS messages sent internationally.
Optional: This property may not always be included.
Example: 6
Name
smsLocalMessages
Type
integer
Status
PREVIEW
Description
Amount of SMS messages sent locally.
Optional: This property may not always be included.
Example: 6
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
updatedAt
Type
string
Status
PREVIEW
Description
The time at which the aggregation was last updated.
Optional: This property may not always be included.
Example: "2024-02-15T12:13:14Z"
Name
voice
Type
integer
Description
Amount of voice usage in seconds.
Example: 240
Name
voiceInternationalSeconds
Type
integer
Status
PREVIEW
Description
Amount of international voice usage in seconds.
Optional: This property may not always be included.
Example: 125
Name
voiceLocalSeconds
Type
integer
Status
PREVIEW
Description
Amount of local voice usage in seconds.
Optional: This property may not always be included.
Example: 6

Example

{
  "object": "usageRecord",
  "data": 18883100,
  "dataDeviceBytes": 30029300,
  "dataTetheringBytes": 30029300,
  "end": "2021-02-15T01:01:01.0Z",
  "labels": {
    "country": "US",
    "roaming": "none",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  },
  "sms": 15,
  "smsInternationalMessages": 6,
  "smsLocalMessages": 6,
  "start": "2021-02-14T01:01:01.0Z",
  "updatedAt": "2024-02-15T12:13:14.0Z",
  "voice": 240,
  "voiceInternationalSeconds": 125,
  "voiceLocalSeconds": 6
}

GET/projects/{project}/subscriptions/{subscription}/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
subscription
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
>= 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 aggregated values for the time range or period requested. The roaming aggregation is in preview and may only be used in particular cases.
Allowed values: daily period country roaming daily,country daily,roaming period,country period,roaming country,daily country,period roaming,daily roaming,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

GET

/projects/{project}/subscriptions/{subscription}/usage

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription}/usage \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "usageRecord",
      "data": 18883100,
      "dataDeviceBytes": 30029300,
      "dataTetheringBytes": 30029300,
      "end": "2021-02-15T00:00:00Z",
      "labels": {
        "country": "US",
        "roaming": "none",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
      },
      "sms": 15,
      "smsInternationalMessages": 6,
      "smsLocalMessages": 6,
      "start": "2021-02-14T00:00:00Z",
      "updatedAt": "2024-02-15T12:13:14Z",
      "voice": 240,
      "voiceInternationalSeconds": 125,
      "voiceLocalSeconds": 6
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/testing/projects/{project}/subscriptions/{subscription}/usage

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
Default: 0
>= 0
Name
dataDevice
Type
nullable integer
Status
PREVIEW
Description
Amount of on-device data used in bytes.
Example: 102938120
Default: 0
>= 0
Name
dataTethering
Type
nullable integer
Status
PREVIEW
Description
Amount of tethering data used in bytes.
Example: 102938120
Default: 0
>= 0
Name
voice
Type
nullable integer
Description
Amount of voice usage in seconds.
Example: 240
Default: 0
>= 0
Name
voiceLocal
Type
nullable integer
Status
PREVIEW
Description
Amount of local voice usage in seconds.
Example: 329
Default: 0
>= 0
Name
voiceInternational
Type
nullable integer
Status
PREVIEW
Description
Amount of international long distance voice usage in seconds.
Example: 329
Default: 0
>= 0
Name
sms
Type
nullable integer
Description
Amount of SMS messages sent and received.
Example: 15
Default: 0
>= 0
Name
smsLocal
Type
nullable integer
Status
PREVIEW
Description
Amount of local SMS messages sent and received.
Example: 4
Default: 0
>= 0
Name
smsInternational
Type
nullable integer
Status
PREVIEW
Description
Amount of international long distance SMS messages sent and received.
Example: 4
Default: 0
>= 0
Name
subscriptionAddon
Type
nullable string
Status
PREVIEW
Description
The unique identifier for the subscription addon to which the simulated usage should be attributed. If not provided, the usage won't be attributed to any add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
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"
Name
roaming
Type
nullable string
Status
PREVIEW
Description
The roaming mode to assign to the simulated usage.
Default: none
Allowed values: none international domestic
Name
usageBalance
Type
nullable string
Status
PREVIEW
Description
The Usage Balance id to assign the simulated usage to.
Example: "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc"
Name
usageBalanceAmount
Type
nullable integer
Status
PREVIEW
Description
The amount of usage to attribute to the specified Usage Balance.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscription
Type
string
required
Description
The unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"

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
dataDeviceBytes
Type
integer
Status
PREVIEW
Description
Amount of on-device data used in bytes.
Optional: This property may not always be included.
Example: 30029300
Name
dataTetheringBytes
Type
integer
Status
PREVIEW
Description
Amount of tethering data used in bytes.
Optional: This property may not always be included.
Example: 30029300
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
roaming
Type
string
Status
PREVIEW
Description
The roaming mode the usage occurred in.
Optional: This property may not always be included.
Allowed values: none international domestic
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 messages sent and received.
Example: 15
Name
smsInternationalMessages
Type
integer
Status
PREVIEW
Description
Amount of SMS messages sent internationally.
Optional: This property may not always be included.
Example: 6
Name
smsLocalMessages
Type
integer
Status
PREVIEW
Description
Amount of SMS messages sent locally.
Optional: This property may not always be included.
Example: 6
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
updatedAt
Type
string
Status
PREVIEW
Description
The time at which the aggregation was last updated.
Optional: This property may not always be included.
Example: "2024-02-15T12:13:14Z"
Name
voice
Type
integer
Description
Amount of voice usage in seconds.
Example: 240
Name
voiceInternationalSeconds
Type
integer
Status
PREVIEW
Description
Amount of international voice usage in seconds.
Optional: This property may not always be included.
Example: 125
Name
voiceLocalSeconds
Type
integer
Status
PREVIEW
Description
Amount of local voice usage in seconds.
Optional: This property may not always be included.
Example: 6

Request

POST

/testing/projects/{project}/subscriptions/{subscription}/usage

curl https://api.gigs.com/testing/projects/${GIGS_PROJECT}/subscriptions/{subscription}/usage \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "data": 18883100,
  "dataDevice": 102938120,
  "dataTethering": 102938120,
  "voice": 240,
  "voiceLocal": 329,
  "voiceInternational": 329,
  "sms": 15,
  "smsLocal": 4,
  "smsInternational": 4,
  "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "country": "US",
  "roaming": "none",
  "usageBalance": "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc"
}'

Responses

{
  "object": "usageRecord",
  "data": 18883100,
  "dataDeviceBytes": 30029300,
  "dataTetheringBytes": 30029300,
  "end": "2021-02-15T00:00:00Z",
  "labels": {
    "country": "US",
    "roaming": "none",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  },
  "sms": 15,
  "smsInternationalMessages": 6,
  "smsLocalMessages": 6,
  "start": "2021-02-14T00:00:00Z",
  "updatedAt": "2024-02-15T12:13:14Z",
  "voice": 240,
  "voiceInternationalSeconds": 125,
  "voiceLocalSeconds": 6
}

{ "object": "usageRecord", "data": 18883100, "dataDeviceBytes": 30029300, "dataTetheringBytes": 30029300, "end": "2021-02-15T01:01:01.0Z", "labels": { "country": "US", "roaming": "none", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" }, "sms": 15, "smsInternationalMessages": 6, "smsLocalMessages": 6, "start": "2021-02-14T01:01:01.0Z", "updatedAt": "2024-02-15T12:13:14.0Z", "voice": 240, "voiceInternationalSeconds": 125, "voiceLocalSeconds": 6 }

List subscription usage records

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscription
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
>= 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 aggregated values for the time range or period requested. The roaming aggregation is in preview and may only be used in particular cases.
Allowed values: daily period country roaming daily,country daily,roaming period,country period,roaming country,daily country,period roaming,daily roaming,period

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription}/usage \ -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${GIGS_TOKEN}" \ -H "Accept: application/json"

{ "object": "list", "items": [ { "object": "usageRecord", "data": 18883100, "dataDeviceBytes": 30029300, "dataTetheringBytes": 30029300, "end": "2021-02-15T00:00:00Z", "labels": { "country": "US", "roaming": "none", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" }, "sms": 15, "smsInternationalMessages": 6, "smsLocalMessages": 6, "start": "2021-02-14T00:00:00Z", "updatedAt": "2024-02-15T12:13:14Z", "voice": 240, "voiceInternationalSeconds": 125, "voiceLocalSeconds": 6 } ], "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
Default: 0
>= 0
Name
dataDevice
Type
nullable integer
Status
PREVIEW
Description
Amount of on-device data used in bytes.
Example: 102938120
Default: 0
>= 0
Name
dataTethering
Type
nullable integer
Status
PREVIEW
Description
Amount of tethering data used in bytes.
Example: 102938120
Default: 0
>= 0
Name
voice
Type
nullable integer
Description
Amount of voice usage in seconds.
Example: 240
Default: 0
>= 0
Name
voiceLocal
Type
nullable integer
Status
PREVIEW
Description
Amount of local voice usage in seconds.
Example: 329
Default: 0
>= 0
Name
voiceInternational
Type
nullable integer
Status
PREVIEW
Description
Amount of international long distance voice usage in seconds.
Example: 329
Default: 0
>= 0
Name
sms
Type
nullable integer
Description
Amount of SMS messages sent and received.
Example: 15
Default: 0
>= 0
Name
smsLocal
Type
nullable integer
Status
PREVIEW
Description
Amount of local SMS messages sent and received.
Example: 4
Default: 0
>= 0
Name
smsInternational
Type
nullable integer
Status
PREVIEW
Description
Amount of international long distance SMS messages sent and received.
Example: 4
Default: 0
>= 0
Name
subscriptionAddon
Type
nullable string
Status
PREVIEW
Description
The unique identifier for the subscription addon to which the simulated usage should be attributed. If not provided, the usage won't be attributed to any add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
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"
Name
roaming
Type
nullable string
Status
PREVIEW
Description
The roaming mode to assign to the simulated usage.
Default: none
Allowed values: none international domestic
Name
usageBalance
Type
nullable string
Status
PREVIEW
Description
The Usage Balance id to assign the simulated usage to.
Example: "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc"
Name
usageBalanceAmount
Type
nullable integer
Status
PREVIEW
Description
The amount of usage to attribute to the specified Usage Balance.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscription
Type
string
required
Description
The unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"

curl https://api.gigs.com/testing/projects/${GIGS_PROJECT}/subscriptions/{subscription}/usage \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${GIGS_TOKEN}" \ -H "Accept: application/json" \ -d '{ "data": 18883100, "dataDevice": 102938120, "dataTethering": 102938120, "voice": 240, "voiceLocal": 329, "voiceInternational": 329, "sms": 15, "smsLocal": 4, "smsInternational": 4, "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "country": "US", "roaming": "none", "usageBalance": "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc" }'

{ "object": "usageRecord", "data": 18883100, "dataDeviceBytes": 30029300, "dataTetheringBytes": 30029300, "end": "2021-02-15T00:00:00Z", "labels": { "country": "US", "roaming": "none", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" }, "sms": 15, "smsInternationalMessages": 6, "smsLocalMessages": 6, "start": "2021-02-14T00:00:00Z", "updatedAt": "2024-02-15T12:13:14Z", "voice": 240, "voiceInternationalSeconds": 125, "voiceLocalSeconds": 6 }