Usage

Get eSIM usage

Retrieves data usage for a specific eSIM. Returns total, used, and remaining data for all active packages.

get/profiles/{profileReference}/esims/{esimReference}/usage

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Path parameters

profileReferencestringrequired

The eSIM's profile reference (16-digit numeric string)

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

Responses

200eSIM usage dataapplication/json

Show response body

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

packagesarray of PackageUsage

Usage details for each active package

Show properties

packageReferencestring

Package reference identifier (23-character opaque token)

externalTransactionIdstring | null

The client's external transaction ID if provided

typestring

Package type: data for mobile data, sms for text messaging, voice for calls

Optionsdatasmsvoice

usageobject

Usage summary with unit

Show properties

totalnumber

Total capacity (MB for data, message count for SMS, seconds for voice)

usednumber

Amount used

remainingnumber

Amount remaining

unitstring

Unit of measurement (MB, sms, or seconds)

OptionsMBsmsseconds

totalsobject

Aggregated usage totals across all packages by type

Show properties

dataone of UsageSummary | option 2

Aggregated data usage (unit MB), null if no data packages

Show properties

UsageSummaryobject

Usage summary with unit

Show properties

totalnumber

Total capacity (MB for data, message count for SMS, seconds for voice)

usednumber

Amount used

remainingnumber

Amount remaining

unitstring

Unit of measurement (MB, sms, or seconds)

OptionsMBsmsseconds

option 2null

smsone of UsageSummary | option 2

Aggregated SMS usage (unit sms), null if no SMS packages

Show properties

UsageSummaryobject

Usage summary with unit

Show properties

totalnumber

Total capacity (MB for data, message count for SMS, seconds for voice)

usednumber

Amount used

remainingnumber

Amount remaining

unitstring

Unit of measurement (MB, sms, or seconds)

OptionsMBsmsseconds

option 2null

voiceone of UsageSummary | option 2

Aggregated voice usage (unit seconds), null if no voice packages

Show properties

UsageSummaryobject

Usage summary with unit

Show properties

totalnumber

Total capacity (MB for data, message count for SMS, seconds for voice)

usednumber

Amount used

remainingnumber

Amount remaining

unitstring

Unit of measurement (MB, sms, or seconds)

OptionsMBsmsseconds

option 2null

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded 500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/usage"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

curl 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/usage"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

{
  "data": {
    "profileReference": "string",
    "esimReference": "123456000000000001",
    "iccid": "string",
    "packages": [
      {
        "packageReference": "C123456XYZDUSR_A1B2C3D4",
        "externalTransactionId": "order-12345",
        "type": "data",
        "usage": {
          "total": 5000,
          "used": 1234.5,
          "remaining": 3765.5,
          "unit": "MB"
        }
      }
    ],
    "totals": {}
  }
}

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}