List recent events

POST

/events/recent

const url = 'https://api.roamex.com/v1/events/recent';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"type":"esim.activated","limit":20}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.roamex.com/v1/events/recent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "esim.activated", "limit": 20 }'

Returns your most recent events, newest first, optionally of one type. pagination.hasMore is true when older events exist beyond limit. The same events go to the webhook endpoints you subscribed to them.

Authorizations

apiKey

Request Body

Optional. An empty body returns the 10 most recent events of every type. A body that is present must be a JSON object.

application/json

object

type

Only events of this type. Any other value returns 400 INVALID_TYPE.

string

Allowed values: esim.provisioned order.created esim.topped_up customer_topup.succeeded wallet.low_balance wallet.topped_up esim.low_data esim.activated esim.expiring_soon

limit

Events to return. A missing, zero or non-numeric value means 10; values are kept between 1 and 50.

integer

default: 10 >= 1 <= 50

Example

{
  "type": "esim.activated",
  "limit": 20
}

Responses

200

The events.

application/json

object

success

required

boolean

events

required

Array<object>

object

required

The event id. The webhook sends it as event_id.

string format: uuid

type

required

esim.provisioned: new eSIMs were provisioned.
order.created: an order paid from your balance was created.
esim.topped_up: an eSIM got more data or days.
customer_topup.succeeded: a traveller paid for a top-up and received it.
wallet.low_balance: your balance fell below your low-balance threshold.
wallet.topped_up: your balance was topped up.
esim.low_data: an eSIM is running low on data.
esim.activated: an eSIM connected for the first time.
esim.expiring_soon: an eSIM is close to its end date.

string

Allowed values: esim.provisioned order.created esim.topped_up customer_topup.succeeded wallet.low_balance wallet.topped_up esim.low_data esim.activated esim.expiring_soon

created_at

required

When the event happened.

string format: date-time

data

required

The event’s fields. They depend on the event type.

object

key

additional properties

any

pagination

required

object

limit

required

integer

returned

required

integer

hasMore

required

boolean

Example

{
  "success": true,
  "events": [
    {
      "id": "00000000-0000-4000-8000-0000000000e1",
      "type": "esim.topped_up",
      "created_at": "2026-10-22T09:12:00+00:00",
      "data": {
        "esim_id": "00000000-0000-4000-8000-0000000000c1",
        "iccid": "8900000000000000000",
        "package_name": "Japan · 1 GB · 7 days",
        "volume_bytes": 1073741824,
        "duration": 7,
        "duration_unit": "DAY",
        "cost_minor": 450,
        "currency": "EUR",
        "new_balance_minor": 23650
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "returned": 1,
    "hasMore": false
  }
}

Headers

X-RateLimit-Limit

integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining

integer

Calls left in the current minute.

X-RateLimit-Reset

integer

When the current window ends, in Unix seconds.

400

INVALID_JSON: the body is not valid JSON, or not a JSON object.
INVALID_TYPE: type is not a known event type. The message lists them.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

401

AUTH_ERROR: the key is missing, malformed, unknown or revoked. The message says which, for example Missing Authorization header, Invalid Authorization header format. Use: Bearer <api_key>, Invalid API key format or Invalid API key.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key"
  }
}

403

AUTH_ERROR: the account is suspended (Your account is suspended. Please contact support.) or rejected (Account is not approved for API access).

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

404

NOT_FOUND: the API is switched off on the platform. Every endpoint answers this before the key is checked, with the message This feature is not available.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "This feature is not available."
  }
}

413

PAYLOAD_TOO_LARGE: the Content-Length header is over 100 KB.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

429

RATE_LIMITED: the account’s per-minute budget for this endpoint group is used up, or too many refused keys came from this IP address. Wait the Retry-After seconds.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait 42 seconds before retrying."
  }
}

Headers

X-RateLimit-Limit

integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining

integer

Calls left in the current minute.

X-RateLimit-Reset

integer

When the current window ends, in Unix seconds.

Retry-After

integer

Seconds to wait before retrying.

500

FETCH_FAILED: the events could not be read.
INTERNAL_ERROR, or AUTH_ERROR with status 500: see the shared errors.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}