> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimmu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get eSIM usage

> Data used over the whole plan. Still answers after the plan has expired. `history` holds the finished days, newest first, and leaves today out; today, still running, is `today_usage_mb`. `total_usage_mb` is both together.

Data used over the whole plan, day by day. Unlike [Get eSIM
status](https://docs.esimmu.com/endpoints/esim-status.md), it still answers after the plan has expired.

* `history` holds the finished days, newest first. Today is not in it.
* `today_usage_mb` is today so far.
* `total_usage_mb` is the two together.


## OpenAPI

````yaml GET /v1/api_partner/partner_order_items/{topup_id}/usage
openapi: 3.1.0
info:
  title: eSIMmu API
  version: 1.0.0
  summary: Order eSIMs from your own systems over HTTP.
  description: >-
    Server-to-server API for eSIMmu API partners.


    **Ordering is asynchronous.** `POST /v1/api_partner/orders` returns `201`
    with one `topup_id` per unit ordered; the eSIM activation data itself
    arrives later as one `esim.issued` webhook per unit. There is no endpoint to
    poll for it.


    **Every request is signed.** Three headers carry an HMAC-SHA256 proof; see
    the `esimmuAccessKey`, `esimmuSignature` and `esimmuTimestamp` security
    schemes, and the Authentication guide for the full recipe and a test vector.


    **The path you sign is not the path in this document.** Paths here are
    relative to the server URL, which already ends in `/api`. The signature
    covers the full request path *including* that prefix:
    `/api/v1/api_partner/orders`, not `/v1/api_partner/orders`.


    **Product IDs (`option_id`) come from `GET /v1/api_partner/products`**, the
    catalogue at your own price. Fetch it daily and cache it.


    **There is no sandbox yet.**
servers:
  - url: https://api.esimmu.com/api
    description: Production
security:
  - esimmuAccessKey: []
    esimmuSignature: []
    esimmuTimestamp: []
tags:
  - name: Products
  - name: Orders
  - name: Refunds
paths:
  /v1/api_partner/partner_order_items/{topup_id}/usage:
    get:
      tags:
        - Orders
      summary: Get eSIM usage
      description: >-
        Data used over the whole plan. Still answers after the plan has expired.
        `history` holds the finished days, newest first, and leaves today out;
        today, still running, is `today_usage_mb`. `total_usage_mb` is both
        together.
      operationId: getEsimUsage
      parameters:
        - $ref: '#/components/parameters/TopupId'
      responses:
        '200':
          description: Usage over the plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsimUsage'
              example:
                iccid: '89852342022598843729'
                today_usage_mb: 1349.21
                total_usage_mb: 5033.99
                history:
                  - date: '2026-11-18'
                    usage_mb: 2336.54
                  - date: '2026-11-17'
                    usage_mb: 1348.24
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ProviderFailed'
components:
  parameters:
    TopupId:
      name: topup_id
      in: path
      required: true
      description: The eSIM, as returned by Create an order and sent in `esim.issued`.
      schema:
        type: string
      example: '202611161200000000000001'
  schemas:
    EsimUsage:
      type: object
      properties:
        iccid:
          type:
            - string
            - 'null'
        today_usage_mb:
          type: number
        total_usage_mb:
          type: number
        history:
          type: array
          description: Finished days, newest first. Today is not included.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              usage_mb:
                type: number
    AuthError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: unauthorized
            message:
              type: string
    ErrorList:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: Signing failed. See Authentication for each message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
          example:
            error:
              code: unauthorized
              message: Invalid signature.
    NotFound:
      description: No eSIM with that `topup_id` on your account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorList'
          example:
            errors:
              - eSIM not found
    ProviderFailed:
      description: The network could not be reached. Retry later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorList'
          example:
            errors:
              - eSIM provider request failed. Please retry later.
  securitySchemes:
    esimmuAccessKey:
      type: apiKey
      in: header
      name: X-Esimmu-Access-Key
      description: Your partner access key. Identifies you on every request.
    esimmuSignature:
      type: apiKey
      in: header
      name: X-Esimmu-Signature
      description: >-
        Lowercase hex HMAC-SHA256 over the five-line string
        `{METHOD}\n{REQUEST_PATH}\n{TIMESTAMP}\n{ACCESS_KEY}\n{BODY_SHA256}`,
        keyed with your **Base64-decoded** secret key.


        `REQUEST_PATH` includes the `/api` prefix and excludes the domain and
        any query string. `BODY_SHA256` is the lowercase hex SHA-256 of the
        exact body bytes you send; for a request with no body, hash the empty
        string. The string always has five lines.
    esimmuTimestamp:
      type: apiKey
      in: header
      name: X-Esimmu-Timestamp
      description: Unix seconds (UTC), within 5 minutes of our clock.

````

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