Commitments (Beta)

Agent-friendly commitment inventory endpoints

List filterable commitment attributes

get

Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types.

Path parameters
org_idstring · uuidRequired
Responses
chevron-right
200

OK

application/json
namestringRequired
fieldstringRequired
typestring · enumRequiredPossible values:
get
/beta/v1/org/{org_id}/commitments/attributes

Get valid values for a filterable commitment attribute

get

Returns the valid values for a specific filterable field. Use this to discover what values can be passed in a filter object. For example, calling with field='type' returns all commitment types like 'Compute', 'EC2Instance', etc.

Path parameters
org_idstring · uuidRequired
fieldstring · min: 1Required
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
only_activebooleanOptional

Only return active commitments (default true)

Default: true
searchstring · nullableOptional

Text search across commitment fields

Default: null
order_bystring · enumOptional

Field to order results by. Includes the monthly-rate metrics (monthly_net_savings, monthly_gross_savings, monthly_premiums, monthly_estimated_rebate) and utilization.

Default: end_datePossible values:
descbooleanOptional

Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.

Default: false
Responses
chevron-right
200

OK

application/json
or
or
or
or
or
or
or
or
or
or
or
get
/beta/v1/org/{org_id}/commitments/attributes/{field}

Get commitment inventory

get

Returns the organization's commitment inventory for the specified provider. By default returns only active commitments. Set only_active=false to include expired and other non-active commitments.

Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
only_activebooleanOptional

Only return active commitments (default true)

Default: true
searchstring · nullableOptional

Text search across commitment fields

Default: null
order_bystring · enumOptional

Field to order results by. Includes the monthly-rate metrics (monthly_net_savings, monthly_gross_savings, monthly_premiums, monthly_estimated_rebate) and utilization.

Default: end_datePossible values:
descbooleanOptional

Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.

Default: false
pageinteger · min: 1OptionalDefault: 1
page_sizeinteger · min: 1 · max: 10000OptionalDefault: 20
Responses
chevron-right
200

OK

application/json
get
/beta/v1/org/{org_id}/commitments

Get commitment portfolio summary

get

Returns an aggregated summary of the organization's active commitment portfolio including total savings, costs, utilization, and breakdowns by term length and commitment type. All metrics are based on the most recent day of usage data.

Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
Responses
chevron-right
200

OK

application/json
total_active_commitmentsintegerOptional

Total number of active commitments

total_guaranteed_commitmentsintegerOptional

Number of Archera Guaranteed Commitments

total_native_commitmentsintegerOptional

Number of native cloud commitments (not guaranteed)

average_utilizationnumberOptional

Cost-weighted average utilization across active commitments (0-1)

expiring_30_daysintegerOptional

Number of commitments expiring in the next 30 days

expiring_90_daysintegerOptional

Number of commitments expiring in the next 90 days

get
/beta/v1/org/{org_id}/commitments/summary

Get commitment details

get

Returns detailed information about a specific commitment including daily utilization data and an attribution summary showing which resources are covered. Optionally specify start_date/end_date for the utilization and attribution data; defaults to the most recent day.

Path parameters
org_idstring · uuidRequired
commitment_idstring · uuidRequired
Query parameters
start_datestring · date · nullableOptional

Start date for utilization/attribution data (YYYY-MM-DD). Defaults to 1 day ago.

Default: null
end_datestring · date · nullableOptional

End date for utilization/attribution data (YYYY-MM-DD). Defaults to today.

Default: null
Responses
chevron-right
200

OK

application/json
idstring · uuidRequired

Unique commitment identifier

provider_reservation_idstringOptional

Cloud provider's ID for this commitment (e.g. AWS reservation ID)

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:
display_namestringOptional

Human-readable commitment name

typestringOptional

Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')

statusstring · enumOptional

Commitment status (e.g. 'active', 'expired', 'queued')

Possible values:
is_activebooleanOptional

Whether the commitment is currently active

is_archera_guaranteedbooleanOptional

Whether this is an Archera Guaranteed Commitment

account_idstring · nullableOptional

Cloud account ID this commitment is in

billing_account_idstring · nullableOptional

Billing/management account ID

start_datestring · date-time · nullableOptional

When the commitment started

end_datestring · date-time · nullableOptional

When the commitment expires

duration_secondsinteger · nullableOptional

Total commitment duration in seconds

guarantee_startstring · date-time · nullableOptional

When the Archera guarantee period started

guarantee_lockin_datestring · date-time · nullableOptional

When the Archera guarantee lock-in period ends

guarantee_methodanyRead-onlyOptional

How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments.

regionstring · nullableOptional

Cloud region (e.g. 'us-east-1')

instance_typestring · nullableOptional

Instance type (e.g. 'm5.xlarge')

instance_familystring · nullableOptional

Instance family (e.g. 'm5')

plan_typestring · nullableOptional

Plan type (e.g. 'Compute', 'EC2Instance')

payment_optionstring · enum · nullableOptional

Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')

Possible values:
offering_classstring · enum · nullableOptional

Offering class (e.g. 'standard', 'convertible')

Possible values:
is_flexibleboolean · nullableOptional

Whether the commitment has instance size flexibility

instance_countinteger · nullableOptional

Number of instances covered

contract_termstring · enum · nullableOptional

Contract term (e.g. 'thirty_day_gris', 'one_year')

Possible values:
utilizationnumber · nullableOptional

Utilization rate (0-1) over the metrics period

commitment_upfront_costnumberOptional

One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options.

period_startstringOptional

Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data.

period_endstringOptional

Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag).

get
/beta/v1/org/{org_id}/commitments/{commitment_id}

Compare offer alternatives across commitments in a portfolio

get

Returns per-commitment offer alternatives plus portfolio-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'how much have I left on the table' / 'what if my portfolio were all 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-commitment resolution exposed for transparency. Each commitment lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Read-only and informational: there is no follow-up write action — active commitments cannot be swapped programmatically. To actually change term length or offer, the user should reach out to support.

Single-commitment drilldown: pass commitment_ids=[single_id] to scope the response to one commitment. Same shape, just one entry in data and per-(term,payment) rollups that span only that commitment.

Sizing & underutilization caveat: candidate grids per commitment are sized from each commitment's SKU usage in the most recent fully-recorded day, NOT from nominal capacity. Per-commitment utilization_warning and the rollup-level low_utilization_commitment_count flag commitments below 50% utilization — for those rows, candidate financials are projected against hours that aren't actually consumed and the comparison is structurally less informative. Surface the count when non-zero so totals are framed honestly.

Rebate handling: current.commitment_financials_monthly_rate.commitment_savings.net is gross - premium (no rebate), apples-to-apples with candidates which have no rebate concept. For an active commitment earning rebate income this differs from commitment_details's net (which includes rebate). For true current economics including rebate, use commitment_details.

Skipped commitments: commitments that fail to build a grid (typically 'no recent SKU usage') are listed in skipped_commitments with a reason, NOT silently dropped. They contribute to neither current_totals nor hypothetical_totals.

Presentation note: partial_upfront and all_upfront candidate offers should be de-emphasized by default — only surface them when an in-scope commitment already has an upfront component or the caller has signaled interest in upfront trades. Use the payment_options query arg to filter.

Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
commitment_idsstring · uuid[] · nullableOptional

Optional subset of commitments to compare. If omitted, defaults to all currently-active commitments for the provider.

Default: null
Responses
chevron-right
200

OK

application/json
get
/beta/v1/org/{org_id}/commitments/comparison

Get commitment portfolio metrics over time

get

Returns daily commitment metrics (savings, costs, utilization, premiums, rebates) over a time period. Includes per-day data points and period totals. Note: coverage is not included here — coverage is a segment-level metric. Use the /metrics/daily-coverage endpoint for coverage trends.

Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
start_datestring · dateRequired

Start date (YYYY-MM-DD)

end_datestring · dateRequired

End date (YYYY-MM-DD, exclusive)

searchstring · nullableOptional

Text search across commitment fields

Default: null
Responses
chevron-right
200

OK

application/json
period_startstringOptional

Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data.

period_endstringOptional

Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag).

utilizationnumberOptional

Cost-weighted average utilization across the period (0-1)

underutilized_commitment_costnumberOptional

Total cost of unused commitment capacity for the period

get
/beta/v1/org/{org_id}/commitments/metrics

Last updated

Was this helpful?