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
    dataTethering
    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
    smsInternational
    Type
    integer
    Status
    PREVIEW
    Description

    Amount of SMS messages sent internationally.

    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
    voice
    Type
    integer
    Description

    Amount of voice usage in seconds.

    Example: 240
  • Name
    voiceInternational
    Type
    integer
    Status
    PREVIEW
    Description

    Amount of international voice usage in seconds.

    Optional: This property may not always be included.
    Example: 125

Example

{
  "object": "usageRecord",
  "data": 18883100,
  "dataTethering": 30029300,
  "end": "2021-02-15T01:01:01.0Z",
  "labels": {
    "country": "US",
    "roaming": "none",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  },
  "sms": 15,
  "smsInternational": 6,
  "start": "2021-02-14T01:01:01.0Z",
  "voice": 240,
  "voiceInternational": 125
}

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 a single aggregated value for the time range or period requested.

    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,
      "dataTethering": 30029300,
      "end": "2021-02-15T00:00:00Z",
      "labels": {
        "country": "US",
        "roaming": "none",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
      },
      "sms": 15,
      "smsInternational": 6,
      "start": "2021-02-14T00:00:00Z",
      "voice": 240,
      "voiceInternational": 125
    }
  ],
  "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".

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
    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
    dataTethering
    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
    smsInternational
    Type
    integer
    Status
    PREVIEW
    Description

    Amount of SMS messages sent internationally.

    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
    voice
    Type
    integer
    Description

    Amount of voice usage in seconds.

    Example: 240
  • Name
    voiceInternational
    Type
    integer
    Status
    PREVIEW
    Description

    Amount of international voice usage in seconds.

    Optional: This property may not always be included.
    Example: 125

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,\"voice\":240,\"sms\":15,\"country\":\"US\"}"

Responses

{
  "object": "usageRecord",
  "data": 18883100,
  "dataTethering": 30029300,
  "end": "2021-02-15T00:00:00Z",
  "labels": {
    "country": "US",
    "roaming": "none",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  },
  "sms": 15,
  "smsInternational": 6,
  "start": "2021-02-14T00:00:00Z",
  "voice": 240,
  "voiceInternational": 125
}