Usage

List usage sessions

Experimental. This endpoint is still settling — its request and response shape may change without a deprecation cycle.

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.

Sessions are built from provider CDRs, so recent sessions may change as files arrive 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 UsageSessionrequired

Usage sessions, newest first (by usageUpdatedAt)

Show properties

dataobject

Show properties

sessionReferencestring · uuidrequired

Stable session identifier

startedAtstring · date-timerequired

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

endedAtstring | null · date-timerequired

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

usageUpdatedAtstring · date-timerequired

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.

usedintegerrequired

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

usageCountrystring | nullrequired

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

networkstring | nullrequired

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

mccstring | nullrequired

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

mncstring | nullrequired

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

tadigstring | nullrequired

Visited operator TADIG code; null when unknown

typestringrequired

unitstringrequired

voiceobject

Show properties

sessionReferencestring · uuidrequired

Stable session identifier

startedAtstring · date-timerequired

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

endedAtstring | null · date-timerequired

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

usageUpdatedAtstring · date-timerequired

usedintegerrequired

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

usageCountrystring | nullrequired

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

networkstring | nullrequired

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

mccstring | nullrequired

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

mncstring | nullrequired

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

tadigstring | nullrequired

Visited operator TADIG code; null when unknown

typestringrequired

unitstringrequired

directionstringrequired

Voice direction; unknown preserves sessions whose provider direction is unavailable

Optionsincomingoutgoingunknown

destinationCountrystring | nullrequired

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

fromNumberstring | nullrequired

Calling party; anonymous indicates provider concealment

toNumberstring | nullrequired

Called party; anonymous indicates provider concealment

smsobject

Show properties

sessionReferencestring · uuidrequired

Stable session identifier

startedAtstring · date-timerequired

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

endedAtstring | null · date-timerequired

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

usageUpdatedAtstring · date-timerequired

usedintegerrequired

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

usageCountrystring | nullrequired

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

networkstring | nullrequired

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

mccstring | nullrequired

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

mncstring | nullrequired

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

tadigstring | nullrequired

Visited operator TADIG code; null when unknown

typestringrequired

unitstringrequired

fromNumberstring | nullrequired

Sending party; anonymous indicates provider concealment

toNumberstring | nullrequired

Receiving party; anonymous indicates provider concealment

paginationobjectrequired

Show properties

limitintegerrequired

Maximum items per page

hasMorebooleanrequired

Whether there are more items after this page

nextCursorstring | nullrequired

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 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/%7BprofileReference%7D/esims/%7BesimReference%7D/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))

}

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/%7BprofileReference%7D/esims/%7BesimReference%7D/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))

}

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",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}