UsageExperimental

Get aggregated usage history

Retrieves historical usage for an eSIM, aggregated per period and usage type, with optional usage-country buckets. Recent periods may still change as additional usage is reported, and totals can differ from the package usage 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 UsagePeriod

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

Show properties

periodStartstring · date-time

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

periodEndstring · date-time

Exclusive period end

usagearray of UsagePeriodEntry

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

dataobjectoptional

Show properties

usednumber

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

usageCountrystringoptional

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

sessionCountinteger

Number of logical usage sessions contributing to this aggregate

typestring

unitstring

voiceobjectoptional

Show properties

usednumber

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

usageCountrystringoptional

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

sessionCountinteger

Number of logical usage sessions contributing to this aggregate

typestring

unitstring

directionstring

Voice direction; unknown preserves usage whose provider direction is unavailable

Optionsincomingoutgoingunknown

destinationCountrystringoptional

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

smsobjectoptional

Show properties

usednumber

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

usageCountrystringoptional

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

sessionCountinteger

Number of logical usage sessions contributing to this aggregate

typestring

unitstring

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}/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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history?from=2026-08-01&aggregation=usageCountry%2Cday"))
    .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/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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/usage/history?from=2026-08-01&aggregation=usageCountry%2Cday"))
    .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": [
    {
      "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",
  "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"
    }
  ]
}