> ## Documentation Index
> Fetch the complete documentation index at: https://telnesstech-a0a16404.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get usage for multiple subscriptions

> Retrieve current usage statistics for multiple subscriptions by providing their IDs.



## OpenAPI

````yaml /api-reference/bundled_openapi.json get /subscriptions/usage
openapi: 3.1.0
info:
  title: Telness Tech Connect
  version: 2.0.0-alpha
  description: >
    Telness Tech Connect API provides all you need to own your user's
    connectivity experience.


    Go back to [Telnesstech.com](https://telnesstech.com)
servers:
  - url: https://apiv2.example.com
    description: Connect API URL for your domain
security:
  - apiKey: []
  - bearerAuth: []
    apiKey: []
tags:
  - name: Auth
    description: Authenticate users and obtain access tokens.
  - name: Users
    description: Manage users.
  - name: Customers
    description: Manage customers.
  - name: Subscriptions
    description: Manage subscriptions and subscription.
  - name: Subscription Addons
    description: Manage subscription addons.
  - name: Subscription Usage
    description: Get subscription usage.
  - name: Subscribers
    description: Manage subscribers.
  - name: Licenses
    description: Manage licenses.
  - name: Product Offerings
    description: Browse product offerings.
  - name: Product Catalogs
    description: Browse product catalogs.
  - name: Product Discounts
    description: Discounts and promotions.
  - name: Orders
    description: Manage orders and line items.
  - name: Payment Intents
    description: >-
      Inspect payment intents, the money collected over card rails for orders
      and renewals.
  - name: Payment Links
    description: Create and manage payment links for orders and invoices.
  - name: Payment Sessions
    description: Create and manage payment sessions for orders.
  - name: Payment Profiles
    description: Manage customer payment profiles and methods.
  - name: Payment Profile Sessions
    description: Create sessions for setting up payment profiles.
  - name: Signing sessions
    description: Handle contract signing sessions for postpaid orders.
  - name: Porting
    description: Manage number porting for subscriptions.
  - name: Taxes
    description: Calculate taxes for products and line items.
  - name: Invoices
    description: Manage invoices and invoice items.
  - name: Tools
    description: >-
      Tools for address validation, number porting, device info, and network
      coverage.
  - name: Inventory
    description: Manage phone number inventory, SIM cards, and reservations.
  - name: Workflows
    description: Dynamic processing of customer journeys and events.
paths:
  /subscriptions/usage:
    get:
      tags:
        - Subscription Usage
      summary: Get usage for multiple subscriptions
      description: >-
        Retrieve current usage statistics for multiple subscriptions by
        providing their IDs.
      operationId: getSubscriptionsUsage
      parameters:
        - name: subscriptionIds
          in: query
          required: true
          description: List of subscription IDs to retrieve usage for.
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 100
      responses:
        '200':
          description: Usage statistics for the requested subscriptions.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                additionalProperties: false
                properties:
                  items:
                    type: array
                    description: Usage information for each requested subscription.
                    items:
                      type: object
                      required:
                        - subscriptionId
                        - usage
                      additionalProperties: false
                      properties:
                        subscriptionId:
                          type: string
                          description: The unique identifier for the subscription.
                          example: 123e4567-e89b-12d3-a456-426614174000
                        usage:
                          $ref: '#/components/schemas/Usage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Usage:
      type: object
      description: >-
        Current usage statistics for a subscription, organized by service type
        with per-package breakdown.
      required:
        - updatedAt
      additionalProperties: false
      properties:
        voice:
          $ref: '#/components/schemas/UsageVoice'
          description: Voice call usage across all scopes and packages.
        sms:
          $ref: '#/components/schemas/UsageSms'
          description: SMS usage across all scopes and packages.
        mms:
          $ref: '#/components/schemas/UsageMms'
          description: MMS usage across all scopes and packages.
        data:
          $ref: '#/components/schemas/UsageData'
          description: Data usage across all scopes and packages.
        updatedAt:
          type: string
          format: date-time
          description: When the usage information was last updated.
          example: '2024-01-15T10:30:00Z'
    UsageVoice:
      type: object
      description: Voice call usage organized by scope.
      additionalProperties: false
      properties:
        national:
          type: array
          description: National voice call packages.
          items:
            $ref: '#/components/schemas/UsageVoicePackage'
        roaming:
          type: array
          description: Roaming voice call packages.
          items:
            $ref: '#/components/schemas/UsageVoicePackage'
        ild:
          type: array
          description: International long distance voice call packages.
          items:
            $ref: '#/components/schemas/UsageVoiceIldPackage'
    UsageSms:
      type: object
      description: SMS usage organized by scope.
      additionalProperties: false
      properties:
        national:
          type: array
          description: National SMS packages.
          items:
            $ref: '#/components/schemas/UsageSmsPackage'
        roaming:
          type: array
          description: Roaming SMS packages.
          items:
            $ref: '#/components/schemas/UsageSmsPackage'
        ild:
          type: array
          description: International long distance SMS packages.
          items:
            $ref: '#/components/schemas/UsageSmsPackage'
    UsageMms:
      type: object
      description: MMS usage organized by scope.
      additionalProperties: false
      properties:
        national:
          type: array
          description: National MMS packages.
          items:
            $ref: '#/components/schemas/UsageMmsPackage'
        roaming:
          type: array
          description: Roaming MMS packages.
          items:
            $ref: '#/components/schemas/UsageMmsPackage'
        ild:
          type: array
          description: International long distance MMS packages.
          items:
            $ref: '#/components/schemas/UsageMmsPackage'
    UsageData:
      type: object
      description: Data usage organized by scope.
      additionalProperties: false
      properties:
        national:
          type: array
          description: National data packages.
          items:
            $ref: '#/components/schemas/UsageDataNationalPackage'
        roaming:
          type: array
          description: Roaming data packages.
          items:
            $ref: '#/components/schemas/UsageDataRoamingPackage'
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error.
        code:
          type: string
          description: A machine-readable code for the error.
        details:
          type: array
          description: Additional details about the error.
          items:
            type: object
            required:
              - message
              - code
            properties:
              message:
                type: string
                description: >-
                  A human-readable message providing more details about the
                  error.
              code:
                type: string
                description: A machine-readable code for the specific detail.
              property:
                type: string
                description: The property or field related to the error.
              suggestion:
                $ref: '#/components/schemas/Any'
                description: >
                  A suggested value for the particular property.


                  For example, this may be set when validating an address with
                  an alias, suggesting the expected value by the operator.
        hint:
          type: string
          description: A hint to help resolve the error.
    UsageVoicePackage:
      type: object
      description: Voice usage for a single package.
      required:
        - name
        - callSeconds
        - callCount
        - callRemainingSeconds
        - callTotalSeconds
        - status
      additionalProperties: false
      properties:
        subscriptionAddonId:
          type: string
          description: The subscription addon this package belongs to, if applicable.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Human-readable name of the package.
          example: Unlimited National
        callSeconds:
          type: integer
          format: int64
          description: Total call duration used in seconds.
          example: 3600
        callCount:
          type: integer
          format: int64
          description: Total number of calls made.
          example: 15
        callRemainingSeconds:
          type: integer
          format: int64
          description: Remaining call seconds in the allowance.
          example: 32400
        callTotalSeconds:
          type: integer
          format: int64
          description: Total call seconds allowance for this package.
          example: 36000
        status:
          $ref: '#/components/schemas/UsagePackageStatus'
          description: The status of this package.
        validFrom:
          type: string
          format: date-time
          description: When this package became active.
          example: '2025-01-01T00:00:00Z'
        validTo:
          type: string
          format: date-time
          description: When this package expires.
          example: '2025-02-01T00:00:00Z'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UsageVoiceIldPackage:
      type: object
      description: International long distance voice package with monetary balance.
      required:
        - name
      additionalProperties: false
      properties:
        subscriptionAddonId:
          type: string
          description: The subscription addon this package belongs to, if applicable.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Human-readable name of the package.
          example: ILD 100 Minutes
        balance:
          type: number
          format: double
          description: Remaining monetary balance for ILD calls.
          example: 15.5
        currency:
          type: string
          description: Currency of the balance.
          example: USD
        expiryDate:
          type: string
          format: date
          x-ogen-type: telnesstech.com/apiv2/apiv2types.Date
          description: When this ILD package expires.
          example: '2025-12-31'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UsageSmsPackage:
      type: object
      description: SMS usage for a single package.
      required:
        - name
        - smsCount
        - smsRemaining
        - smsTotal
        - status
      additionalProperties: false
      properties:
        subscriptionAddonId:
          type: string
          description: The subscription addon this package belongs to, if applicable.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Human-readable name of the package.
          example: 500 SMS National
        smsCount:
          type: integer
          format: int64
          description: Number of SMS messages sent.
          example: 25
        smsRemaining:
          type: integer
          format: int64
          description: Remaining SMS in the allowance.
          example: 475
        smsTotal:
          type: integer
          format: int64
          description: Total SMS allowance for this package.
          example: 500
        status:
          $ref: '#/components/schemas/UsagePackageStatus'
          description: The status of this package.
        validFrom:
          type: string
          format: date-time
          description: When this package became active.
          example: '2025-01-01T00:00:00Z'
        validTo:
          type: string
          format: date-time
          description: When this package expires.
          example: '2025-02-01T00:00:00Z'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UsageMmsPackage:
      type: object
      description: MMS usage for a single package.
      required:
        - name
        - mmsCount
        - mmsRemaining
        - mmsTotal
      additionalProperties: false
      properties:
        subscriptionAddonId:
          type: string
          description: The subscription addon this package belongs to, if applicable.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Human-readable name of the package.
          example: 100 MMS National
        mmsCount:
          type: integer
          format: int64
          description: Number of MMS messages sent.
          example: 10
        mmsRemaining:
          type: integer
          format: int64
          description: Remaining MMS in the allowance.
          example: 90
        mmsTotal:
          type: integer
          format: int64
          description: Total MMS allowance for this package.
          example: 100
        validFrom:
          type: string
          format: date-time
          description: When this package became active.
          example: '2025-01-01T00:00:00Z'
        validTo:
          type: string
          format: date-time
          description: When this package expires.
          example: '2025-02-01T00:00:00Z'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UsageDataNationalPackage:
      type: object
      description: >-
        National data usage for a single package, including RLAH (Roam Like At
        Home) data if applicable.
      required:
        - name
        - dataBytesUsed
        - dataBytesRemaining
        - dataBytesTotal
        - status
      additionalProperties: false
      properties:
        subscriptionAddonId:
          type: string
          description: The subscription addon this package belongs to, if applicable.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Human-readable name of the package.
          example: Europe 10GB
        dataBytesUsed:
          type: integer
          format: int64
          description: Data used in bytes.
          example: 3221225472
        dataBytesRemaining:
          type: integer
          format: int64
          description: Remaining data in bytes.
          example: 7516192768
        dataBytesTotal:
          type: integer
          format: int64
          description: Total data allowance in bytes.
          example: 10737418240
        rlahBytesUsed:
          type: integer
          format: int64
          description: >-
            RLAH (Roam Like At Home) data used in bytes within this national
            package.
          example: 1073741824
        rlahBytesRemaining:
          type: integer
          format: int64
          description: Remaining RLAH data in bytes.
          example: 4294967296
        rlahBytesTotal:
          type: integer
          format: int64
          description: Total RLAH data allowance in bytes.
          example: 5368709120
        status:
          $ref: '#/components/schemas/UsagePackageStatus'
          description: The status of this package.
        validFrom:
          type: string
          format: date-time
          description: When this package became active.
          example: '2025-01-01T00:00:00Z'
        validTo:
          type: string
          format: date-time
          description: When this package expires.
          example: '2025-02-01T00:00:00Z'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UsageDataRoamingPackage:
      type: object
      description: Roaming data usage for a single package.
      required:
        - name
        - dataBytesUsed
        - dataBytesRemaining
        - dataBytesTotal
        - status
      additionalProperties: false
      properties:
        subscriptionAddonId:
          type: string
          description: The subscription addon this package belongs to, if applicable.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Human-readable name of the package.
          example: Asia 5GB Roaming
        dataBytesUsed:
          type: integer
          format: int64
          description: Data used in bytes.
          example: 1073741824
        dataBytesRemaining:
          type: integer
          format: int64
          description: Remaining data in bytes.
          example: 4294967296
        dataBytesTotal:
          type: integer
          format: int64
          description: Total data allowance in bytes.
          example: 5368709120
        status:
          $ref: '#/components/schemas/UsagePackageStatus'
          description: The status of this package.
        validFrom:
          type: string
          format: date-time
          description: When this package became active.
          example: '2025-01-01T00:00:00Z'
        validTo:
          type: string
          format: date-time
          description: When this package expires.
          example: '2025-02-01T00:00:00Z'
        metadata:
          $ref: '#/components/schemas/Metadata'
    Any:
      oneOf:
        - type: string
        - type: number
        - type: boolean
        - type: object
          additionalProperties: true
        - type: array
    UsagePackageStatus:
      type: string
      description: Current status of the usage package in its lifecycle.
      enum:
        - ACTIVE
        - NOT_ACTIVE
        - EXPIRED
    Metadata:
      type: object
      additionalProperties:
        type: string
      description: >
        A set of key-value pairs that can be attached to an object for storing
        additional information in a semi-structured format.
  responses:
    BadRequest:
      description: The request was malformed or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access to this resource is forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >
        An API key that grants access to the Connect API. You can create and
        manage API keys in the portal.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Bearer authentication with JWT tokens is used to authenticate users.


        Do note that a valid API keys is also required to access the Connect API
        to prove that requests are made by a trusted party.


        Requests with a JWT token is scoped to the permissions of the user the
        token belongs to, regardless of the API key used.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.