Usage

Get eSIM usage

Retrieves data usage for a specific eSIM. Returns total, used, and remaining data for all active packages. Usage reflects what the network has reported so far, so recent activity can take a while to appear.

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

dataobjectoptional

Show properties

profileReferencestringoptional

esimReferencestringoptional

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

packagesarray of PackageUsageoptional

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

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

Examplesdatasmsvoice

usageobject

Usage summary with unit

Show properties

totalnumberoptional

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

usednumberoptional

Amount used

remainingnumberoptional

Amount remaining

unitstringoptional

Extensible enum. Unit of measurement: MB, sms or seconds.

ExamplesMBsmsseconds

totalsobjectoptional

Aggregated usage totals across all packages by type

Show properties

dataobject | null

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

Show properties

totalnumberoptional

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

usednumberoptional

Amount used

remainingnumberoptional

Amount remaining

unitstringoptional

Extensible enum. Unit of measurement: MB, sms or seconds.

ExamplesMBsmsseconds

smsobject | null

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

Show properties

totalnumberoptional

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

usednumberoptional

Amount used

remainingnumberoptional

Amount remaining

unitstringoptional

Extensible enum. Unit of measurement: MB, sms or seconds.

ExamplesMBsmsseconds

voiceobject | null

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

Show properties

totalnumberoptional

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

usednumberoptional

Amount used

remainingnumberoptional

Amount remaining

unitstringoptional

Extensible enum. Unit of measurement: MB, sms or seconds.

ExamplesMBsmsseconds

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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": {
      "data": {
        "total": 5000,
        "used": 1234.5,
        "remaining": 3765.5,
        "unit": "MB"
      },
      "sms": {
        "total": 5000,
        "used": 1234.5,
        "remaining": 3765.5,
        "unit": "MB"
      },
      "voice": {
        "total": 5000,
        "used": 1234.5,
        "remaining": 3765.5,
        "unit": "MB"
      }
    }
  }
}

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