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
    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/{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

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/{subscription}/usage
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
}