Usage

Get aggregated usage history

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

Retrieves historical usage for an eSIM, aggregated per period and usage type, with optional usage-country buckets. Built from provider CDRs: recent periods may still change as files arrive, and totals can differ from the live counters returned by the packages endpoints.

from/to are wall-clock timestamps interpreted in timezone — they must not carry a zone designator (Z or offset) and must fall on the temporal aggregation boundary in that timezone (midnight for day, first of month for month). On the DST fall-back day a day period genuinely contains 25 hours; a spring-forward wall-clock gap is resolved by shifting across the gap.

Usage is attributed to the period containing the session's usageUpdatedAt. For every period the aggregated total exactly equals the sum of the sessions listed by the sessions endpoint for the same window; data usage is reported as whole bytes on both.

Every requested period is returned. Periods without usage have an empty usage array. Usage is always grouped by type. aggregation accepts grouping dimensions followed by a temporal period: day produces daily totals, while usageCountry,day produces daily totals per country where usage occurred and includes usageCountry in each country bucket. Voice is always additionally grouped by direction, and outgoing voice by destination country when known.

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

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

fromstringrequired

Period start (inclusive). Wall-clock in timezone, no zone designator, aligned to aggregation, and no more than 3 calendar months before the current wall-clock time.

tostring

Period end (exclusive, so a full period ends at the start of the next one). Same format and alignment as from; defaults to the next aggregation boundary after now (the in-progress period is included). Maximum span and lookback are 3 calendar months.

aggregationstringrequired

Comma-separated grouping dimensions followed by period size. Supported periods are hour, day, and month; usageCountry adds buckets for the country where usage occurred. Voice is always split by direction, and outgoing voice by destination country. Spans longer than 7 days require a day or month period.

OptionshourdaymonthusageCountry,hourusageCountry,dayusageCountry,month

timezonestring

Allowed IANA timezone used to interpret from/to and cut period boundaries.

OptionsUTCEurope/AmsterdamEurope/BerlinEurope/BrusselsEurope/LondonEurope/ParisAmerica/New_YorkAmerica/Los_AngelesAsia/SingaporeAsia/TokyoAustralia/Sydney

DefaultUTC

Responses

200Aggregated usage per periodapplication/json

Show response body

dataarray of UsagePeriodrequired

One entry per period, oldest first. Periods without any usage are included with an empty usage array.

Show properties

periodStartstring · date-timerequired

Inclusive period start, RFC 3339 with the requested timezone's offset

periodEndstring · date-timerequired

Exclusive period end

usagearray of UsagePeriodEntryrequired

Usage in this period, always split by type. The optional usageCountry dimension applies to every type. Voice is always split by direction, and outgoing voice by destination country when known. Only observed combinations are included.

Show properties

dataobject

Show properties

usednumberrequired

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

usageCountrystring

ISO 3166-1 alpha-2 country where usage occurred, produced by the usageCountry aggregation dimension

sessionCountintegerrequired

Number of logical usage sessions contributing to this aggregate

typestringrequired

unitstringrequired

voiceobject

Show properties

usednumberrequired

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

usageCountrystring

ISO 3166-1 alpha-2 country where usage occurred, produced by the usageCountry aggregation dimension

sessionCountintegerrequired

Number of logical usage sessions contributing to this aggregate

typestringrequired

unitstringrequired

directionstringrequired

Voice direction; unknown preserves usage whose provider direction is unavailable

Optionsincomingoutgoingunknown

destinationCountrystring

ISO 3166-1 alpha-2 destination country for outgoing voice, omitted when unknown or not applicable

smsobject

Show properties

usednumberrequired

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

usageCountrystring

ISO 3166-1 alpha-2 country where usage occurred, produced by the usageCountry aggregation dimension

sessionCountintegerrequired

Number of logical usage sessions contributing to this aggregate

typestringrequired

unitstringrequired

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}/usage/history?from=2026-08-01&aggregation=usageCountry,day' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history?from=2026-08-01&aggregation=usageCountry,day', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
    params={
      "from": "2026-08-01",
      "aggregation": "usageCountry,day"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ],
  'query' => [
    'from' => '2026-08-01',
    'aggregation' => 'usageCountry,day'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/usage/history?from=2026-08-01&aggregation=usageCountry,day"

	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/history?from=2026-08-01&aggregation=usageCountry,day' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history?from=2026-08-01&aggregation=usageCountry,day', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
    params={
      "from": "2026-08-01",
      "aggregation": "usageCountry,day"
    }
)

$client = new GuzzleHttp\Client();

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

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/usage/history?from=2026-08-01&aggregation=usageCountry,day"

	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": [
    {
      "periodStart": "2026-08-12T00:00:00+02:00",
      "periodEnd": "2026-08-13T00:00:00+02:00",
      "usage": [
        {
          "type": "data",
          "used": 1190378209,
          "unit": "bytes",
          "usageCountry": "NL",
          "sessionCount": 42
        },
        {
          "type": "voice",
          "used": 380,
          "unit": "seconds",
          "direction": "outgoing",
          "destinationCountry": "US",
          "usageCountry": "NL",
          "sessionCount": 3
        }
      ]
    },
    {
      "periodStart": "2026-08-13T00:00:00+02:00",
      "periodEnd": "2026-08-14T00:00:00+02:00",
      "usage": []
    }
  ]
}

{
  "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"
    }
  ]
}