openapi: 3.2.0
info:
  title: Twilio Usage Records API
  version: 1.52.0
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://www.twilio.com/legal/tos
  description: 'Operations tagged UsageRecords across 2 of this provider''s published API definitions: super-sim-openapi-original.yml, wireless-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://supersim.twilio.com
- url: https://wireless.twilio.com
tags:
- name: Usage Records
paths:
  /v1/UsageRecords:
    servers:
    - url: https://supersim.twilio.com
    description: Usage information for Sim resources
    x-twilio:
      defaultOutputProperties:
      - account_sid
      - period
      pathType: list
    get:
      description: List UsageRecords
      tags:
      - Usage Records
      parameters:
      - name: Sim
        in: query
        description: SID or unique name of a Sim resource. Only show UsageRecords representing usage incurred by this Super SIM.
        schema:
          type: string
      - name: Fleet
        in: query
        description: SID or unique name of a Fleet resource. Only show UsageRecords representing usage for Super SIMs belonging to this Fleet resource at the time the usage occurred.
        schema:
          type: string
      - name: Network
        in: query
        description: SID of a Network resource. Only show UsageRecords representing usage on this network.
        schema:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^HW[0-9a-fA-F]{32}$
      - name: IsoCountry
        in: query
        description: Alpha-2 ISO Country Code. Only show UsageRecords representing usage in this country.
        schema:
          type: string
          format: iso-country-code
      - name: Group
        in: query
        description: 'Dimension over which to aggregate usage records. Can be: `sim`, `fleet`, `network`, `isoCountry`. Default is to not aggregate across any of these dimensions, UsageRecords will be aggregated into the time buckets described by the `Granularity` parameter.'
        schema:
          type: string
          $ref: '#/components/schemas/usage_record_enum_group'
      - name: Granularity
        in: query
        description: 'Time-based grouping that UsageRecords should be aggregated by. Can be: `hour`, `day`, or `all`. Default is `all`. `all` returns one UsageRecord that describes the usage for the entire period.'
        schema:
          type: string
          $ref: '#/components/schemas/usage_record_enum_granularity'
      - name: StartTime
        in: query
        description: Only include usage that occurred at or after this time, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Default is one month before the `end_time`.
        schema:
          type: string
          format: date-time
      - name: EndTime
        in: query
        description: Only include usage that occurred before this time (exclusive), specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Default is the current time.
        schema:
          type: string
          format: date-time
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsageRecordResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListUsageRecord
      x-maturity:
      - Beta
      summary: List usage record
      x-summary-source: derived
components:
  schemas:
    supersim.v1.usage_record:
      type: object
      properties:
        account_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that incurred the usage.
        sim_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^HS[0-9a-fA-F]{32}$
          description: SID of a Sim resource to which the UsageRecord belongs. Value will only be present when either a value for the `Sim` query parameter is provided or when UsageRecords are grouped by `sim`. Otherwise, the value will be `null`.
        network_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^HW[0-9a-fA-F]{32}$
          description: SID of the Network resource the usage occurred on. Value will only be present when either a value for the `Network` query parameter is provided or when UsageRecords are grouped by `network`. Otherwise, the value will be `null`.
        fleet_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^HF[0-9a-fA-F]{32}$
          description: SID of the Fleet resource the usage occurred on. Value will only be present when either a value for the `Fleet` query parameter is provided or when UsageRecords are grouped by `fleet`. Otherwise, the value will be `null`.
        iso_country:
          type:
          - string
          - 'null'
          format: iso-country-code
          description: Alpha-2 ISO Country Code that the usage occurred in. Value will only be present when either a value for the `IsoCountry` query parameter is provided or when UsageRecords are grouped by `isoCountry`. Otherwise, the value will be `null`.
        period:
          description: The time period for which the usage is reported. The period is represented as a pair of `start_time` and `end_time` timestamps specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        data_upload:
          type:
          - integer
          - 'null'
          format: int64
          description: Total data uploaded in bytes, aggregated by the query parameters.
        data_download:
          type:
          - integer
          - 'null'
          format: int64
          description: Total data downloaded in bytes, aggregated by the query parameters.
        data_total:
          type:
          - integer
          - 'null'
          format: int64
          description: Total of data_upload and data_download.
        data_total_billed:
          type:
          - number
          - 'null'
          description: Total amount in the `billed_unit` that was charged for the data uploaded or downloaded. Will return 0 for usage prior to February 1, 2022. Value may be 0 despite `data_total` being greater than 0 if the data usage is still being processed by Twilio's billing system. Refer to [Data Usage Processing](https://www.twilio.com/docs/iot/supersim/api/usage-record-resource#data-usage-processing) for more details.
        billed_unit:
          type:
          - string
          - 'null'
          format: currency
          description: The currency in which the billed amounts are measured, specified in the 3 letter ISO 4127 format (e.g. `USD`, `EUR`, `JPY`). This can be null when data_toal_billed is 0 and we do not yet have billing information for the corresponding data usage. Refer to [Data Usage Processing](https://www.twilio.com/docs/iot/supersim/api/usage-record-resource#data-usage-processing) for more details.
    ListUsageRecordResponse:
      type: object
      properties:
        usage_records:
          type: array
          items:
            $ref: '#/components/schemas/supersim.v1.usage_record'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type:
              - string
              - 'null'
              format: uri
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type:
              - string
              - 'null'
              format: uri
            url:
              type: string
              format: uri
            key:
              type: string
    usage_record_enum_group:
      type: string
      enum:
      - sim
      - fleet
      - network
      - isoCountry
    usage_record_enum_granularity:
      type: string
      enum:
      - hour
      - day
      - all
    ListAccountUsageRecordResponse:
      type: object
      properties:
        usage_records:
          type: array
          items:
            $ref: '#/components/schemas/wireless.v1.account_usage_record'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type:
              - string
              - 'null'
              format: uri
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type:
              - string
              - 'null'
              format: uri
            url:
              type: string
              format: uri
            key:
              type: string
    wireless.v1.account_usage_record:
      type: object
      properties:
        account_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created the AccountUsageRecord resource.
        period:
          description: The time period for which usage is reported. Contains `start` and `end` properties that describe the period using GMT date-time values specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        commands:
          description: An object that describes the aggregated Commands usage for all SIMs during the specified period. See [Commands Usage Object](https://www.twilio.com/docs/iot/wireless/api/account-usagerecord-resource#commands-usage-object).
        data:
          description: An object that describes the aggregated Data usage for all SIMs over the period. See [Data Usage Object](https://www.twilio.com/docs/iot/wireless/api/account-usagerecord-resource#data-usage-object).
    account_usage_record_enum_granularity:
      type: string
      enum:
      - hourly
      - daily
      - all
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
x-refined-from:
- super-sim-openapi-original.yml
- wireless-openapi-original.yml
x-maturity:
- name: GA
  description: This product is Generally Available.
- name: Beta
  description: PLEASE NOTE that this is a Beta product that is subject to change. Use it with caution.