---
title: "List AWS Reserved Instances"
method: GET
path: "/ps4commitments/v1/aws/payer-accounts/{payerAccountId}/reserved-instances"
tags: ["PS4Commitments AWS"]
---

# List AWS Reserved Instances

`GET /ps4commitments/v1/aws/payer-accounts/{payerAccountId}/reserved-instances`

Returns the paginated list of Reserved Instances (RIs) for the specified MPA.
Filterable by state, instance type/family, region, and offering class.

## Path parameters

- `payerAccountId` string, required

## Query parameters

- `status` 'active' | 'retired' | 'payment_pending' | 'payment_failed' | 'queued' | 'queued_deleted'
- `instanceType` string
- `instanceFamily` string
- `region` string
- `offeringClass` 'standard' | 'convertible'
- `pageToken` string
- `maxResults` integer

## Headers

- `X-Tenant-Id` string

## Response `200`

Paginated list of Reserved Instances.

- object
  - `items` AwsReservedInstance[], required
    - `commitmentId` string, required — Reserved Instance ID (AWS-assigned).
    - `reservedInstanceArn` string, nullable — Full ARN of the Reserved Instance, when known.
    - `accountId` string, required — AWS account ID where the Reserved Instance exists.
    - `state` 'active' | 'retired' | 'payment_pending' | 'payment_failed' | 'queued' | 'queued_deleted', required — Reserved Instance state, tracking the AWS EC2 Reserved Instance API verbatim in external snake_case form. Differs from Savings Plan states by design — for example, the terminal state is `retired` here vs `expired` on Savings Plans.
    - `instanceType` string, required — EC2 instance type on which the RI can be used (e.g. `m5.large`).
    - `instanceCount` integer, nullable
    - `instanceTenancy` string — Tenancy of the instance (e.g. `default`, `dedicated`).
    - `availabilityZone` string, nullable
    - `region` string, nullable
    - `platform` string, nullable
    - `description` string — Product platform description.
    - `scope` string — Scope of the Reserved Instance (e.g. `Availability Zone`, `Region`).
    - `offeringClass` 'standard' | 'convertible'
    - `offeringType` string — RI offering type (e.g. `All Upfront`).
    - `termDuration` 'one_year' | 'three_year' — Commitment term length.
    - `durationSeconds` integer, nullable — RI duration in seconds.
    - `startTime` string, date-time, nullable
    - `endTime` string, date-time, nullable
    - `currencyCode` string — ISO 4217 currency code (USD in practice).
    - `fixedPrice` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `usagePrice` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `hourlyRecurringFee` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `upfrontFee` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `totalAssetValue` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `averageOnDemandHourlyRate` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `amortizedRecurringFee` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `amortizedUpfrontFee` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `totalAmortizedFee` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `netRiSavings` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `realizedSavings` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `unrealizedSavings` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `totalPotentialRiSavings` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `onDemandCostOfRiHoursUsed` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `riCostForUnusedHours` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `purchasedHours` integer, nullable
    - `purchasedUnits` integer, nullable
    - `totalActualHours` integer, nullable
    - `totalNormalizedUnits` integer, nullable
    - `unusedHours` integer, nullable
    - `unusedNormalizedUnits` integer, nullable
    - `utilizationPercentage` number, double, nullable — Cost-explorer reported utilization percentage (0–1).
    - `utilizationPercentageInUnits` number, double, nullable
    - `mtdSavings` Money, required
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `mtdUtilization` number, double, nullable — Month-to-date utilization (0–1). Null when not yet available. A stored 0% is indistinguishable from unavailable and is returned as null.
    - `updatedAt` string, date-time, nullable — Timestamp of the last successful inventory sync for this Reserved Instance.
    - `recurringCharges` AwsReservedInstanceRecurringCharge[]
      - `amount` number, double, required — The amount of the recurring charge.
      - `frequency` string, required — The frequency of the recurring charge (e.g. `Hourly`).
  - `pageToken` string, nullable
  - `rowCount` integer, nullable — Best-effort count for the filtered result set. May be null or omitted for expensive counts.

## Other responses

- `400` — Syntactically malformed request, missing required parameter, or unsupported parameter value.
- `401` — Missing or invalid credentials.
- `403` — Authenticated but not authorised to access this customer's PS4C resources.
- `404` — The requested resource does not exist.
- `500` — Unexpected server error.
- `503` — Service temporarily unavailable; retry after the indicated delay.

---

[API](https://skmtc.dev/doit/apis/doit-cloud-intelligence.md) · [All operations](https://skmtc.dev/doit/apis/doit-cloud-intelligence/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/doit/doit-cloud-intelligence/revisions/9416402fc119/schema)