UsageExperimental

List usage sessions

Retrieves individual usage sessions (data sessions, calls, SMS) for an eSIM, newest first, covering the last 3 calendar months. Passing from and to together filters the listing to sessions that ended at or after from and before to.

Recent sessions may change as additional usage is reported, and a session's started can precede the requested window. Data session usage is returned as whole bytes; voice and SMS usage use seconds and message counts respectively. Concealed calling/called numbers are returned as the fixed string anonymous.

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

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)

Query parameters

fromstring

Includes sessions whose usageUpdatedAt is at or after this RFC 3339 UTC timestamp. Provide it together with to. It can reach at most 3 calendar months into the past.

tostring

Includes sessions whose usageUpdatedAt is before this RFC 3339 UTC timestamp. Provide it together with from.

limitinteger

Maximum number of sessions per page.

Default100

cursorstring

Opaque cursor token for fetching the next page. Pass the nextCursor value from a previous response.

Responses

200Usage sessionsapplication/json

Show response body

dataarray of UsageSession

Usage sessions, newest first (by usageUpdatedAt)

Show properties

dataobjectoptional

Show properties

sessionReferencestring · uuid

Stable session identifier

startedAtstring · date-time

Session/call start (UTC). Can precede the requested window for long sessions.

endedAtstring | null · date-time

Session/call end (UTC); null while the session is open

usageUpdatedAtstring · date-time

End of the last reported usage window (UTC). An open session keeps accumulating usage; when comparing two reads of the same sessionReference, the one with the later usageUpdatedAt is the current state.

usedinteger

Amount used in unit; data usage is reported as whole bytes

usageCountrystring | null

ISO 3166-1 alpha-2 country the SIM was in, null when unknown

networkstring | null

Operator network the session used, as named at usage time; null when unknown

mccstring | null

Visited network E.212 mobile country code; null when unknown

mncstring | null

Visited network E.212 mobile network code (leading zeros significant); null when unknown

tadigstring | null

Visited operator TADIG code; null when unknown

typestring

unitstring

voiceobjectoptional

Show properties

sessionReferencestring · uuid

Stable session identifier

startedAtstring · date-time

Session/call start (UTC). Can precede the requested window for long sessions.

endedAtstring | null · date-time

Session/call end (UTC); null while the session is open

usageUpdatedAtstring · date-time

usedinteger

Amount used in unit; data usage is reported as whole bytes

usageCountrystring | null

ISO 3166-1 alpha-2 country the SIM was in, null when unknown

networkstring | null

Operator network the session used, as named at usage time; null when unknown

mccstring | null

Visited network E.212 mobile country code; null when unknown

mncstring | null

Visited network E.212 mobile network code (leading zeros significant); null when unknown

tadigstring | null

Visited operator TADIG code; null when unknown

typestring

unitstring

directionstring

Voice direction; unknown preserves sessions whose provider direction is unavailable

Optionsincomingoutgoingunknown

destinationCountrystring | null

Country inferred from the outgoing destination number; null when unknown or not applicable

fromNumberstring | null

Calling party; anonymous indicates provider concealment

toNumberstring | null

Called party; anonymous indicates provider concealment

smsobjectoptional

Show properties

sessionReferencestring · uuid

Stable session identifier

startedAtstring · date-time

Session/call start (UTC). Can precede the requested window for long sessions.

endedAtstring | null · date-time

Session/call end (UTC); null while the session is open

usageUpdatedAtstring · date-time

usedinteger

Amount used in unit; data usage is reported as whole bytes

usageCountrystring | null

ISO 3166-1 alpha-2 country the SIM was in, null when unknown

networkstring | null

Operator network the session used, as named at usage time; null when unknown

mccstring | null

Visited network E.212 mobile country code; null when unknown

mncstring | null

Visited network E.212 mobile network code (leading zeros significant); null when unknown

tadigstring | null

Visited operator TADIG code; null when unknown

typestring

unitstring

fromNumberstring | null

Sending party; anonymous indicates provider concealment

toNumberstring | null

Receiving party; anonymous indicates provider concealment

paginationobject

Show properties

limitinteger

Maximum items per page

hasMoreboolean

Whether there are more items after this page

nextCursorstring | null

Opaque cursor token for the next page. Null when there are no more results.

400Bad request - invalid parameters 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}/sessions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

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

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/sessions', [
  '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}/sessions"

	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}/sessions"))
    .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}/sessions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/sessions",
    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}/sessions', [
  '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}/sessions"

	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}/sessions"))
    .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": [
    {
      "type": "data",
      "unit": "bytes",
      "sessionReference": "01912d68-783e-7cc3-9c15-6a3f2e4b8d01",
      "startedAt": "2026-08-11T22:51:43Z",
      "endedAt": "2026-08-12T01:23:45Z",
      "usageUpdatedAt": "2026-08-12T01:23:45Z",
      "used": 210239488,
      "usageCountry": "NL",
      "network": "KPN B.V.",
      "mcc": "204",
      "mnc": "08",
      "tadig": "NLKPN"
    },
    {
      "type": "voice",
      "unit": "seconds",
      "sessionReference": "01912d68-9f21-7a45-8b02-1c9e5d7f3a02",
      "startedAt": "2026-08-11T21:14:02Z",
      "endedAt": "2026-08-11T21:16:10Z",
      "usageUpdatedAt": "2026-08-11T21:16:10Z",
      "used": 128,
      "usageCountry": "NL",
      "network": "KPN B.V.",
      "mcc": "204",
      "mnc": "08",
      "tadig": "NLKPN",
      "direction": "outgoing",
      "destinationCountry": "US",
      "fromNumber": "31612345678",
      "toNumber": "12125550123"
    }
  ],
  "pagination": {
    "limit": 100,
    "hasMore": false,
    "nextCursor": null
  }
}

{
  "type": "https://developers.firsty.app/errors/validation_failed",
  "code": "validation_failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}