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

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.

overview, err := client.Commitments.GetOverview(ctx, &levelfour.GetOverviewAPIV1CommitmentsOverviewGetRequest{
    CommitmentType: levelfour.String("sp"),
})

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.

reservations, err := client.Commitments.GetInventory(ctx, &levelfour.GetInventoryAPIV1CommitmentsInventoryGetRequest{
    Instrument: "ri",
    Service:    levelfour.String("rds"),
    State:      levelfour.String("active"),
})

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.

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"),
})

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.

coverage, err := client.Commitments.GetCoverageRates(ctx, &levelfour.GetCoverageRatesAPIV1CommitmentsCoverageRatesGetRequest{})

A provider LevelFour has not measured yet reports measured: false rather than zero coverage.

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.

esr, err := client.Commitments.GetEsr(ctx, &levelfour.GetEsrAPIV1CommitmentsEsrGetRequest{
    Period: levelfour.String("2026-08"),
})

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.

portfolio, err := client.Commitments.GetPortfolio(ctx, &levelfour.GetPortfolioAPIV1CommitmentsPortfolioGetRequest{
    Basis: levelfour.String("net"),
})

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.

byService, err := client.Commitments.GetByService(ctx, &levelfour.GetByServiceAPIV1CommitmentsByServiceGetRequest{})

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.

uncovered, err := client.Commitments.GetUncovered(ctx)

Get recommendations

Returns the commitments worth buying. commitment_type is all (default), ri or sp.

toBuy, err := client.Commitments.GetRecommendations(ctx, &levelfour.GetRecommendationsAPIV1CommitmentsRecommendationsGetRequest{
    CommitmentType: levelfour.String("sp"),
})

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.

contracts, err := client.Commitments.GetContracts(ctx)

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.

detail, err := client.Commitments.GetDetail(ctx, "arn:aws:savingsplans::123456789012:savingsplan/abcd1234")

plan, err := client.Commitments.GetRenewalPlan(ctx, "arn:aws:savingsplans::123456789012:savingsplan/abcd1234")

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.

curl -s "https://api.levelfour.ai/api/v1/commitments/renewal-options/arn%3Aaws%3Asavingsplans%3A%3A123456789012%3Asavingsplan%2Fabcd1234" \
  -H "Authorization: Bearer $LEVELFOUR_API_KEY"

Next

• l4 commitments reads the same data from a terminal
• API reference is every parameter and response field
• Recommendations covers acting on a purchase once it is raised