# Commitments > Read your Reserved Instances and Savings Plans over the API: what you hold, how well you use it, how much of the bill it covers, your effective savings rate, and what renewing each one costs. Source: https://docs.levelfour.ai/resources/commitments The commitments methods read the Reserved Instances and Savings Plans your organization holds: each one's state, how much of it you use, how much of your eligible bill it covers, and what replacing it costs when it expires. They are reads, and any key can call them. The examples show the Go SDK and plain HTTP. A commitment id is the id AWS gives it. A Savings Plan's is an ARN, which contains colons and a slash, so quote it on a command line and URL-encode it in a path. ## Methods | Method | Returns | | --------------------------------------------------------- | --------------------------------------------------------------------------------------- | | [Get overview](#get-overview) | Your effective savings rate and the headline Reserved Instance and Savings Plan figures | | [Get inventory](#get-inventory) | Every commitment you hold, one row each, with the state AWS reports | | [Get utilization](#get-utilization) | How much of what you bought you used, per service or plan type | | [Get coverage rates](#get-coverage-rates) | How much of the eligible bill a commitment covers, per service and per account | | [Get effective savings rate](#get-effective-savings-rate) | What your usage cost against what it would have cost on demand | | [Get portfolio](#get-portfolio) | One row per commitment across every account, with expiry and utilization trend | | [Get by service](#get-by-service) | Utilization and coverage per service and instrument | | [Get uncovered base](#get-uncovered-base) | On-demand spend no commitment covers, split for sizing | | [Get recommendations](#get-recommendations) | Commitments worth buying | | [Get contracts](#get-contracts) | Marketplace and contract commitments that bill like one | | [Get one commitment](#get-one-commitment) | The detail and the renewal plan for one commitment | | [Price a renewal](#price-a-renewal) | Every term an expiring commitment could be replaced with, and what each costs | ## Get overview Returns your effective savings rate and the aggregate figures for Reserved Instances and Savings Plans. AWS carries real figures. Other providers return zeros. **Go** ```go overview, err := client.Commitments.GetOverview(ctx, &levelfour.GetOverviewAPIV1CommitmentsOverviewGetRequest{ CommitmentType: levelfour.String("sp"), }) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/overview?commitment_type=sp" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` `commitment_type` is `all` (default), `ri` or `sp`. `provider` defaults to `aws`. ## Get inventory Returns every commitment of one instrument, one row each. The state is the one AWS reports, not one worked out from the end date: a plan that starts next month is `queued`, and one whose payment failed is `payment-failed`, neither running nor expired. A field only some services carry arrives as null, not zero. **Go** ```go reservations, err := client.Commitments.GetInventory(ctx, &levelfour.GetInventoryAPIV1CommitmentsInventoryGetRequest{ Instrument: "ri", Service: levelfour.String("rds"), State: levelfour.String("active"), }) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/inventory?instrument=ri&service=rds&state=active" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` | Parameter | Type | Description | | ------------ | -------- | -------------------------------------------------------------------------------------- | | `instrument` | `string` | Required. `ri` for Reserved Instances, `sp` for Savings Plans | | `service` | `string` | Limit to one service | | `state` | `string` | `active`, `queued`, `queued-deleted`, `payment-pending`, `payment-failed` or `retired` | | `provider` | `string` | Defaults to `aws` | ## Get utilization Returns how much of what you bought you used, over a window. Reservations come back one entry per service and plans one per plan type, each measured on its own. They are never averaged together: EC2 and RDS reservations are sized in vCPU while Redshift, ElastiCache, OpenSearch and MemoryDB are sized in nodes, so one average would describe neither. Each entry's headline is used hours divided by purchased hours. **Go** ```go utilization, err := client.Commitments.GetUtilization(ctx, &levelfour.GetUtilizationAPIV1CommitmentsUtilizationGetRequest{ Type: levelfour.String("ri"), Start: levelfour.String("2026-06-01"), End: levelfour.String("2026-08-31"), Granularity: levelfour.String("monthly"), }) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/utilization?type=ri&start=2026-06-01&end=2026-08-31&granularity=monthly" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` | Parameter | Type | Description | | -------------- | -------- | ------------------------------ | | `type` | `string` | `ri` (default) or `sp` | | `start`, `end` | `string` | `YYYY-MM-DD` | | `granularity` | `string` | `daily` (default) or `monthly` | ## Get coverage rates Returns how much of the bill that could be covered is covered: per service, and the covered spend per account that consumed it, with the on-demand remainder beside it so the percentage shows what it is a percentage of. Figures are weighted by the dollars behind them, so a small reservation cannot move the number as much as a large one. **Go** ```go coverage, err := client.Commitments.GetCoverageRates(ctx, &levelfour.GetCoverageRatesAPIV1CommitmentsCoverageRatesGetRequest{}) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/coverage-rates" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` A provider LevelFour has not measured yet reports `measured: false` rather than zero coverage. > **Warning** > > `GetCoverage` (`/api/v1/commitments/coverage`) is deprecated. It has one row per commitment, so usage nothing covers never appears in it. Use coverage rates. ## Get effective savings rate Returns what your usage would have cost at public on-demand rates against what it actually cost, for the organization and for each account. The rate is split into what a negotiated agreement earns and what commitments earn, so an account that owns no commitment does not look well covered only because of a discount. **Go** ```go esr, err := client.Commitments.GetEsr(ctx, &levelfour.GetEsrAPIV1CommitmentsEsrGetRequest{ Period: levelfour.String("2026-08"), }) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/esr?period=2026-08" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` `scope` is `eligible` (default), which counts only spend a commitment could cover, or `all`. `period` is a `YYYY-MM` month. ## Get portfolio Returns one row per commitment across every connected account. Each row names the account that holds it and the accounts that consume it, with the expiry time, the utilization trend, and, kept apart, what a renewal protects and what resizing would save. **Go** ```go portfolio, err := client.Commitments.GetPortfolio(ctx, &levelfour.GetPortfolioAPIV1CommitmentsPortfolioGetRequest{ Basis: levelfour.String("net"), }) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/portfolio?basis=net" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` `basis` is `net` (default), what you pay, or `list`, public prices. ## Get by service Returns a service by instrument grid of utilization, coverage, unused and uncovered values, one row for each service that holds at least one commitment. **Go** ```go byService, err := client.Commitments.GetByService(ctx, &levelfour.GetByServiceAPIV1CommitmentsByServiceGetRequest{}) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/by-service" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` ## Get uncovered base Returns the on-demand spend no commitment covers, split by platform and by how much it varies. Each part carries its hourly floor beside its average, because a commitment sized to the average of a spiky base commits more than the base can sustain. **Go** ```go uncovered, err := client.Commitments.GetUncovered(ctx) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/uncovered" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` ## Get recommendations Returns the commitments worth buying. `commitment_type` is `all` (default), `ri` or `sp`. **Go** ```go toBuy, err := client.Commitments.GetRecommendations(ctx, &levelfour.GetRecommendationsAPIV1CommitmentsRecommendationsGetRequest{ CommitmentType: levelfour.String("sp"), }) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/recommendations?commitment_type=sp" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` ## Get contracts Returns commitments that bill like one but appear in no provider commitment view, such as a Marketplace contract, with the contracted floor kept apart from the metered charge that bills on top. **Go** ```go contracts, err := client.Commitments.GetContracts(ctx) ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/contracts" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` ## Get one commitment The detail of one commitment, and its renewal plan: what to buy to replace it and when. The plan gives the moment after which buying is safe, not only a date, because a replacement bills from the moment it is bought. It also lists pending changes that should land first, so their capacity is not locked in for another term. **Go** ```go detail, err := client.Commitments.GetDetail(ctx, "arn:aws:savingsplans::123456789012:savingsplan/abcd1234") plan, err := client.Commitments.GetRenewalPlan(ctx, "arn:aws:savingsplans::123456789012:savingsplan/abcd1234") ``` **HTTP** ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/renewal-plan/arn%3Aaws%3Asavingsplans%3A%3A123456789012%3Asavingsplan%2Fabcd1234" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` ## Price a renewal Three reads price the replacement for an expiring commitment. Go SDK v0.2.0 predates them, so the example is plain REST. | Endpoint | Returns | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /api/v1/commitments/renewal-options/{commitment_id}` | The contract priced again as it stands, beside every other term it is sold on today, each at a range of quantities, with exactly one recommended. Pass `quantity` to price every offering at that quantity instead. A reservation is sold in whole units, so a fractional quantity is a 422 | | `GET /api/v1/commitments/renewal-quote/{commitment_id}` | What replacing it costs today, priced from the current offering. A lookup that failed comes back in `error_message`, so an unpriced renewal reads as unpriced rather than as zero | | `GET /api/v1/commitments/renewal/{commitment_id}` | The renewal purchase already raised for this commitment, or a 404 when there is none | ```bash curl -s "https://api.levelfour.ai/api/v1/commitments/renewal-options/arn%3Aaws%3Asavingsplans%3A%3A123456789012%3Asavingsplan%2Fabcd1234" \ -H "Authorization: Bearer $LEVELFOUR_API_KEY" ``` > **Note** > > Raising the renewal itself happens in the dashboard, not over the API. It commits the organization to a new term, so only a signed-in person with permission to renew can raise it, and the purchase it creates waits for approval like any other saving. [Renewals](/commitments/renewals) walks through it. ## Next * [`l4 commitments`](/cli/commands/commitments) reads the same data from a terminal * [API reference](/api-reference/commitments) is every parameter and response field * [Recommendations](/resources/recommendations) covers acting on a purchase once it is raised