Commitments (Beta)
Agent-friendly commitment inventory endpoints
Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types.
OK
Bad request
Unauthorized
Forbidden
Not found
Method not allowed
Conflict
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments/attributes HTTP/1.1
Accept: */*
[
{
"name": "text",
"field": "text",
"type": "boolean"
}
]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.
Cloud provider (aws, azure, gcp)
awsPossible values: Only return the default inventory scope (default true). By default this includes active commitments and commitments with status=recently_expired.
trueWhen only_active=true, include commitments with status=recently_expired (default true). Set false for strictly active commitments.
trueText search across commitment fields
nullField to order results by. Includes the monthly-rate metrics (monthly_net_savings, monthly_gross_savings, monthly_premiums, monthly_estimated_rebate) and utilization.
end_datePossible values: Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.
falseOK
Bad request
Unauthorized
Forbidden
Not found
Method not allowed
Conflict
Unprocessable Content
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments/attributes/{field}?provider=aws HTTP/1.1
Accept: */*
{
"name": "text",
"field": "text",
"type": "boolean",
"filters": [
{
"field": "text",
"value": "text",
"op": "="
}
]
}Returns the organization's commitment inventory for the specified provider. By default returns active commitments plus commitments with status=recently_expired. Set include_recently_expired=false for strictly active commitments, or only_active=false to include expired and other non-active commitments.
Cloud provider (aws, azure, gcp)
awsPossible values: Only return the default inventory scope (default true). By default this includes active commitments and commitments with status=recently_expired.
trueWhen only_active=true, include commitments with status=recently_expired (default true). Set false for strictly active commitments.
trueText search across commitment fields
nullField to order results by. Includes the monthly-rate metrics (monthly_net_savings, monthly_gross_savings, monthly_premiums, monthly_estimated_rebate) and utilization.
end_datePossible values: Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.
false120OK
Bad request
Unauthorized
Forbidden
Not found
Method not allowed
Conflict
Unprocessable Content
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments?provider=aws HTTP/1.1
Accept: */*
[
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"provider_reservation_id": "text",
"order_id": null,
"provider": "aws",
"display_name": "text",
"guaranteed_display_name": "text",
"type": "text",
"status": "active",
"is_active": true,
"is_archera_guaranteed": true,
"account_id": "text",
"billing_account_id": "text",
"start_date": "2026-01-01T00:00:00.000Z",
"end_date": "2026-01-01T00:00:00.000Z",
"duration_seconds": 1,
"guarantee_start": "2026-01-01T00:00:00.000Z",
"guarantee_lockin_date": "2026-01-01T00:00:00.000Z",
"guarantee_method": null,
"region": "text",
"instance_type": "text",
"instance_family": "text",
"plan_type": "text",
"payment_option": "no_upfront",
"offering_class": "standard",
"is_flexible": true,
"instance_count": 1,
"contract_term": "one_year_gris",
"utilization": 1,
"commitment_upfront_cost": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
}
}
]Returns an aggregated summary of the organization's current commitment inventory including total savings, costs, utilization, and breakdowns by term length and commitment type. By default includes commitments with status=recently_expired; set include_recently_expired=false for strictly active commitments. All metrics are based on the most recent day of usage data.
Cloud provider (aws, azure, gcp)
awsPossible values: Include commitments with status=recently_expired in the current inventory summary (default true). Set false for a strictly active summary.
trueOK
Total number of commitments in the summary scope. By default this includes active commitments and status=recently_expired commitments.
Number of commitments in the summary scope with is_active=true.
Number of commitments with status=recently_expired included in this summary scope. Zero when include_recently_expired=false.
Number of Archera Guaranteed Commitments in the summary scope
Number of native cloud commitments (not guaranteed) in the summary scope
Cost-weighted average utilization across the summary scope (0-1)
Number of commitments expiring in the next 30 days
Number of commitments expiring in the next 90 days
Bad request
Unauthorized
Forbidden
Not found
Method not allowed
Conflict
Unprocessable Content
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments/summary?provider=aws HTTP/1.1
Accept: */*
{
"total_commitments": 1,
"total_active_commitments": 1,
"recently_expired_commitments": 1,
"total_guaranteed_commitments": 1,
"total_native_commitments": 1,
"average_utilization": 1,
"expiring_30_days": 1,
"expiring_90_days": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
},
"by_term": [
{
"label": "text",
"count": 1,
"average_utilization": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
}
}
],
"by_type": [
{
"label": "text",
"count": 1,
"average_utilization": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
}
}
]
}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.
Start date for utilization/attribution data (YYYY-MM-DD). Defaults to 1 day ago.
nullEnd date for utilization/attribution data (YYYY-MM-DD). Defaults to today.
nullOK
Archera-internal commitment identifier. Use it as the commitment_id input to other endpoints. It is not shown in the Archera UI or the cloud console, so do not present it to users as their commitment id — use provider_reservation_id.
Cloud provider's id for this commitment — the value the Archera UI labels 'Commitment ID' and the one users recognize from their cloud console. AWS: reservation id or savings plan id (e.g. 'ri-0abc…', 'sp-0abc…'). Azure: reservation id or savings plan id (the GUID after the last '/' of the ARM id); see order_id for the order. GCP: committed use discount id; resource-based CUDs are stored per resource type as ':<RESOURCE_TYPE>' (e.g. '123:VCPU' and '123:MEMORY' are one console CUD), spend-based CUDs have no suffix.
Azure only — reservation order id or savings plan order id that groups this commitment in the Azure portal. Null for AWS and GCP.
Cloud provider (aws, azure, gcp)
Human-readable commitment name
Commitment name when held as an Archera Guaranteed Commitment
Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')
Commitment status (e.g. 'active', 'expired', 'queued')
Whether the commitment is currently active
Whether this is an Archera Guaranteed Commitment
Cloud account ID this commitment is in
Billing/management account ID
When the commitment started
When the commitment expires
Total commitment duration in seconds
When the Archera guarantee period started
When the Archera guarantee lock-in period ends
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.
Cloud region (e.g. 'us-east-1')
Instance type (e.g. 'm5.xlarge')
Instance family (e.g. 'm5')
Plan type (e.g. 'Compute', 'EC2Instance')
Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')
Offering class (e.g. 'standard', 'convertible')
Whether the commitment has instance size flexibility
Number of instances covered
Contract term (e.g. 'thirty_day_gris', 'one_year')
Utilization rate (0-1) over the metrics period
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.
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.
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).
Bad request
Unauthorized
Forbidden
Not found
Method not allowed
Conflict
Unprocessable Content
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments/{commitment_id} HTTP/1.1
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"provider_reservation_id": "text",
"order_id": null,
"provider": "aws",
"display_name": "text",
"guaranteed_display_name": "text",
"type": "text",
"status": "active",
"is_active": true,
"is_archera_guaranteed": true,
"account_id": "text",
"billing_account_id": "text",
"start_date": "2026-01-01T00:00:00.000Z",
"end_date": "2026-01-01T00:00:00.000Z",
"duration_seconds": 1,
"guarantee_start": "2026-01-01T00:00:00.000Z",
"guarantee_lockin_date": "2026-01-01T00:00:00.000Z",
"guarantee_method": null,
"region": "text",
"instance_type": "text",
"instance_family": "text",
"plan_type": "text",
"payment_option": "no_upfront",
"offering_class": "standard",
"is_flexible": true,
"instance_count": 1,
"contract_term": "one_year_gris",
"utilization": 1,
"commitment_upfront_cost": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
},
"period_start": "text",
"period_end": "text",
"daily_utilizations": [
{
"date": "2026-01-01",
"active_hours": 1,
"utilization": 1,
"commitment_financials_daily_total": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
}
}
],
"attribution_summary": [
{
"service": "text",
"account_id": "text",
"region": "text",
"resource_type": "text",
"resource_count": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
},
"attributed_utilization": 1
}
],
"covered_resources": [
{
"resource_id": "text",
"name": "text",
"covered_usage": 1,
"total_usage": 1,
"coverage_pct": 1
}
]
}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.
Cloud provider (aws, azure, gcp)
awsPossible values: Optional subset of commitments to compare. If omitted, defaults to all currently-active commitments for the provider.
nullOK
Bad Request
Unauthorized
Forbidden
Not Found
Method not allowed
Conflict
Unprocessable Content
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments/comparison?provider=aws HTTP/1.1
Accept: */*
{
"current_totals": {
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
},
"commitment_upfront_cost": 1
},
"hypothetical_totals": [
{
"contract_term": "one_year_gris",
"payment_option": "no_upfront",
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
},
"commitment_upfront_cost": 1,
"delta_vs_current": {
"monthly_net_savings": 1,
"monthly_commitment_cost": 1,
"upfront_cost": 1
},
"commitments": [
{
"commitment_id": "123e4567-e89b-12d3-a456-426614174000",
"actual_term": "one_year_gris",
"actual_payment_option": "no_upfront",
"actual_commitment_type": "text",
"actual_term_reason": "exact_match",
"utilization_warning": true
}
],
"low_utilization_commitment_count": 1
}
],
"data": [
{
"commitment_id": "123e4567-e89b-12d3-a456-426614174000",
"current": {
"commitment": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"provider_reservation_id": "text",
"order_id": null,
"provider": "aws",
"display_name": "text",
"guaranteed_display_name": "text",
"type": "text",
"status": "active",
"is_active": true,
"is_archera_guaranteed": true,
"account_id": "text",
"billing_account_id": "text",
"start_date": "2026-01-01T00:00:00.000Z",
"end_date": "2026-01-01T00:00:00.000Z",
"duration_seconds": 1,
"guarantee_start": "2026-01-01T00:00:00.000Z",
"guarantee_lockin_date": "2026-01-01T00:00:00.000Z",
"guarantee_method": null,
"region": "text",
"instance_type": "text",
"instance_family": "text",
"plan_type": "text",
"payment_option": "no_upfront",
"offering_class": "standard",
"is_flexible": true,
"instance_count": 1,
"contract_term": "one_year_gris"
},
"commitment_type": "text",
"utilization": 1,
"discount_rate": 1,
"breakeven_days": 1,
"commitment_upfront_cost": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
}
},
"candidates": [
{
"offer_id": "123e4567-e89b-12d3-a456-426614174000",
"offer_org_id": "text",
"offer": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "aws",
"type": "text",
"region": "text",
"duration_seconds": 1,
"instance_type": "text",
"instance_family": "text",
"offering_class": "standard",
"payment_option": "no_upfront",
"plan_type": "text",
"product_description": "text",
"display_name": "text",
"guaranteed_display_name": "text",
"is_flexible": true
},
"lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",
"selected_amount": 1,
"commitment_type": "text",
"contract_term": "one_year_gris",
"payment_option": "no_upfront",
"discount_rate": 1,
"breakeven_days": 1,
"commitment_upfront_cost": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
},
"delta_vs_current": {
"monthly_net_savings": 1,
"upfront_cost": 1,
"discount_rate": 1,
"breakeven_days": 1
}
}
]
}
],
"skipped_commitments": [
{
"commitment_id": "123e4567-e89b-12d3-a456-426614174000",
"reason": "text"
}
]
}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.
Cloud provider (aws, azure, gcp)
awsPossible values: Start date (YYYY-MM-DD)
End date (YYYY-MM-DD, exclusive)
Text search across commitment fields
nullOK
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.
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).
Cost-weighted average utilization across the period (0-1)
Total cost of unused commitment capacity for the period
Bad request
Unauthorized
Forbidden
Not found
Method not allowed
Conflict
Unprocessable Content
Internal server error
Default error response
GET /beta/v1/org/{org_id}/commitments/metrics?provider=aws&start_date=2026-01-01&end_date=2026-01-01 HTTP/1.1
Accept: */*
{
"period_start": "text",
"period_end": "text",
"utilization": 1,
"underutilized_commitment_cost": 1,
"commitment_financials_period_total": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
},
"data": [
{
"date": "text",
"utilization": 1,
"underutilized_commitment_cost": 1,
"commitment_financials_daily_total": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1,
"rebate": 1
},
"covered_ondemand_cost": 1
}
}
]
}Last updated
Was this helpful?