> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onroamly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List your eSIMs

> Every eSIM purchased by the account this API key belongs to,
newest first, with installation details and the latest usage
reading.

Paginate with `starting_after`, passing the `id` of the last eSIM
from the previous page. `meta.hasMore` tells you when to stop.




## OpenAPI

````yaml /openapi.yaml get /v1/esims
openapi: 3.0.3
info:
  title: Roamly API
  version: 1.0.0
  description: |
    Programmatic access to Roamly's travel eSIM plan catalog — every
    destination we sell, every plan, with live pricing.

    **Base URL:** `https://api.onroamly.com`

    All endpoints are read-only `GET` requests returning JSON, and require
    an API key sent as `Authorization: Bearer rk_live_…`. Keys are managed
    from your [Roamly account](https://www.onroamly.com/account/api).
  contact:
    name: Roamly
    email: hello@onroamly.com
    url: https://www.onroamly.com
servers:
  - url: https://api.onroamly.com
security:
  - bearerAuth: []
tags:
  - name: Destinations
    description: Countries and regional bundles Roamly sells plans for.
  - name: Plans
    description: The sellable plan catalog.
  - name: eSIMs
    description: >
      eSIMs purchased by your own account. Every key is tied to one Roamly
      account and returns only that account's eSIMs.
paths:
  /v1/esims:
    get:
      tags:
        - eSIMs
      summary: List your eSIMs
      description: |
        Every eSIM purchased by the account this API key belongs to,
        newest first, with installation details and the latest usage
        reading.

        Paginate with `starting_after`, passing the `id` of the last eSIM
        from the previous page. `meta.hasMore` tells you when to stop.
      operationId: listEsims
      parameters:
        - name: limit
          in: query
          required: false
          description: How many to return (1–200).
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: starting_after
          in: query
          required: false
          description: The `id` of the last eSIM on the previous page.
          schema:
            type: string
      responses:
        '200':
          description: Your eSIMs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Esim'
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                      hasMore:
                        type: boolean
                      nextCursor:
                        type: string
                        description: >-
                          Pass as `starting_after` for the next page. Absent on
                          the last page.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Esim:
      type: object
      properties:
        id:
          type: string
          example: 8Kd0kQ2mXpLz1vRb3nTy
        status:
          type: string
          description: >
            `paid` on purchase, `provisioning` while we issue it, `ready` once
            installable, then `expired` or `depleted` at end of life. `failed`
            means provisioning didn't complete.
          enum:
            - paid
            - provisioning
            - ready
            - failed
            - expired
            - depleted
        plan:
          type: object
          properties:
            name:
              type: string
              example: Japan 5GB 30 days
            destination:
              type: object
              properties:
                code:
                  type: string
                  example: JP
                name:
                  type: string
                  example: Japan
                type:
                  type: string
                  enum:
                    - country
                    - region
            dataAmountGB:
              type: number
              nullable: true
              example: 5
            dataType:
              type: string
              enum:
                - total
                - daily
            validityDays:
              type: integer
              nullable: true
              example: 30
            speed:
              type: string
              nullable: true
              example: 4G/5G
        esim:
          type: object
          description: Installation details. Populated once `status` is `ready`.
          properties:
            iccid:
              type: string
              nullable: true
            activationCode:
              type: string
              nullable: true
              description: The LPA string, for manual installation.
            qrCodeUrl:
              type: string
              nullable: true
            iosInstallUrl:
              type: string
              nullable: true
              description: One-tap universal link that opens iOS eSIM setup.
            androidInstallUrl:
              type: string
              nullable: true
            apn:
              type: string
              nullable: true
            pin:
              type: string
              nullable: true
            puk:
              type: string
              nullable: true
        usage:
          type: object
          description: Latest reading from our hourly poll — `updatedAt` says how fresh.
          properties:
            usedMB:
              type: number
              nullable: true
            remainingMB:
              type: number
              nullable: true
            totalMB:
              type: number
              nullable: true
            updatedAt:
              type: string
              format: date-time
              nullable: true
        price:
          $ref: '#/components/schemas/Money'
        purchasedAt:
          type: string
          format: date-time
          nullable: true
        fulfilledAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
    Money:
      type: object
      properties:
        amount:
          type: number
          format: float
          example: 14.5
        currency:
          type: string
          enum:
            - AUD
            - USD
          example: AUD
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: not_found
            message:
              type: string
              example: Unknown route.
  responses:
    Unauthorized:
      description: Missing, malformed, unknown, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: missing_api_key
              message: 'Provide your API key as ''Authorization: Bearer rk_live_…''.'
    RateLimited:
      description: Rate limit exceeded (120 requests/minute per key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded (120 requests/minute per key).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your Roamly API key, e.g. `Authorization: Bearer rk_live_…`'

````