# Commitments (Beta)

Agent-friendly commitment inventory endpoints

## List filterable commitment attributes

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

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/attributes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List filterable commitment attributes","tags":["Commitments (Beta)"],"description":"Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a filterable commitment attribute

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/attributes/{field}":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"only_active","description":"Only return active commitments (default true)","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"search","description":"Text search across commitment fields","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Examples: {\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute\"} — categorical; {\"field\": \"end_date\", \"op\": \"<\", \"value\": \"2026-06-01\"} — expiring before June 2026; {\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000} — saving more than $1000/month. Date-dependent metric fields are 730-hour monthly rates matching `commitment_financials_monthly_rate.*` in the response: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the monthly-rate metrics (`monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`) and `utilization`.","schema":{"type":"string","default":"end_date","enum":["start_date","end_date","type","account_id","upfront_cost","monthly_cloud_provider_cost","monthly_recurring_cost","is_archera_guaranteed","duration_seconds","is_active","utilization","monthly_net_savings","monthly_gross_savings","monthly_premiums","monthly_estimated_rebate"]},"required":false},{"in":"query","name":"desc","description":"Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Get valid values for a filterable commitment attribute","tags":["Commitments (Beta)"],"description":"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."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment inventory

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"only_active","description":"Only return active commitments (default true)","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"search","description":"Text search across commitment fields","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Examples: {\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute\"} — categorical; {\"field\": \"end_date\", \"op\": \"<\", \"value\": \"2026-06-01\"} — expiring before June 2026; {\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000} — saving more than $1000/month. Date-dependent metric fields are 730-hour monthly rates matching `commitment_financials_monthly_rate.*` in the response: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the monthly-rate metrics (`monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`) and `utilization`.","schema":{"type":"string","default":"end_date","enum":["start_date","end_date","type","account_id","upfront_cost","monthly_cloud_provider_cost","monthly_recurring_cost","is_archera_guaranteed","duration_seconds","is_active","utilization","monthly_net_savings","monthly_gross_savings","monthly_premiums","monthly_estimated_rebate"]},"required":false},{"in":"query","name":"desc","description":"Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":10000},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentWithMetrics"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment inventory","description":"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."}}},"components":{"schemas":{"CommitmentWithMetrics":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"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."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"utilization":{"type":"number","description":"Utilization rate (0-1) over the metrics period","nullable":true},"commitment_upfront_cost":{"type":"number","description":"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."},"commitment_financials_monthly_rate":{"description":"Commitment economics as 730-hour monthly rates — cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment portfolio summary

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/summary":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentSummary"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment portfolio summary","description":"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."}}},"components":{"schemas":{"CommitmentSummary":{"type":"object","properties":{"total_active_commitments":{"type":"integer","description":"Total number of active commitments"},"total_guaranteed_commitments":{"type":"integer","description":"Number of Archera Guaranteed Commitments"},"total_native_commitments":{"type":"integer","description":"Number of native cloud commitments (not guaranteed)"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization across active commitments (0-1)"},"expiring_30_days":{"type":"integer","description":"Number of commitments expiring in the next 30 days"},"expiring_90_days":{"type":"integer","description":"Number of commitments expiring in the next 90 days"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials aggregated across all active commitments. commitment_savings.rebate is the sum of rebates across commitments.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"by_term":{"type":"array","description":"Breakdown by term length. Guaranteed commitments are grouped by their guarantee period (e.g. '30-Day Guaranteed', '1-Year Guaranteed'), native commitments by their cloud term (e.g. '1-Year Native', '3-Year Native').","items":{"$ref":"#/components/schemas/BreakdownEntry"}},"by_type":{"type":"array","description":"Breakdown by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')","items":{"$ref":"#/components/schemas/BreakdownEntry"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"BreakdownEntry":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of commitments in this group"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization within this group (0-1)"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. commitment_savings.rebate is the sum of rebates for commitments in this group.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment details

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/{commitment_id}":{"get":{"parameters":[{"in":"query","name":"start_date","description":"Start date for utilization/attribution data (YYYY-MM-DD). Defaults to 1 day ago.","schema":{"type":"string","format":"date","default":null,"nullable":true},"required":false},{"in":"query","name":"end_date","description":"End date for utilization/attribution data (YYYY-MM-DD). Defaults to today.","schema":{"type":"string","format":"date","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment details","description":"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."}}},"components":{"schemas":{"CommitmentDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"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."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"utilization":{"type":"number","description":"Utilization rate (0-1) over the metrics period","nullable":true},"commitment_upfront_cost":{"type":"number","description":"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."},"commitment_financials_monthly_rate":{"description":"Commitment economics as 730-hour monthly rates — cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"period_start":{"type":"string","description":"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_end":{"type":"string","description":"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)."},"daily_utilizations":{"type":"array","description":"Daily utilization data points for the effective time period","items":{"$ref":"#/components/schemas/DailyUtilization"}},"attribution_summary":{"type":"array","description":"Resources covered by this commitment, aggregated by service, account, region, and resource type","items":{"$ref":"#/components/schemas/AttributionSummaryEntry"}}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of this data point"},"active_hours":{"type":"number","description":"Hours the commitment was active on this day (0-24)","nullable":true},"utilization":{"type":"number","description":"Utilization rate for this day (0-1)"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day (NOT a monthly rate). commitment_savings.rebate is the rebate accrued on this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"AttributionSummaryEntry":{"type":"object","properties":{"service":{"type":"string","description":"Cloud service name","nullable":true},"account_id":{"type":"string","description":"Cloud account ID","nullable":true},"region":{"type":"string","description":"Cloud region","nullable":true},"resource_type":{"type":"string","description":"Resource type — instance family for compute, usage type for other services, or SKU name as fallback","nullable":true},"resource_count":{"type":"integer","description":"Number of resources in this group"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. cloud_provider_cost has `{total}` only — per-group data doesn't split into recurring / amortized_upfront. archera_premium is allocated proportionally by cloud_provider_cost share of the parent commitment; summing across groups yields the parent commitment's monthly premium. commitment_savings has no rebate field at this level — rebate is a commitment-wide concept.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"attributed_utilization":{"type":"number","description":"Share of the commitment's overall utilization attributed to this group (0-1). All groups' attributed_utilization values sum to the commitment's total utilization."}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Compare offer alternatives across commitments in a portfolio

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/comparison":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"commitment_ids","description":"Optional subset of commitments to compare. If omitted, defaults to all currently-active commitments for the provider.","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"contract_terms","description":"Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any commitment's candidates after the payment-option filter.","schema":{"type":"array","default":null,"items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"payment_options","description":"Payment options to include. Defaults to no_upfront only — most users are uncomfortable with cash at signing, so this matches the default framing for portfolio comparisons. Pass partial_upfront / all_upfront explicitly to surface those.","schema":{"type":"array","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentOfferComparisonResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Compare offer alternatives across commitments in a portfolio","description":"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.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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."}}},"components":{"schemas":{"CommitmentOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Portfolio-wide totals for the commitments currently in scope today. Use as the baseline when interpreting hypothetical deltas.","allOf":[{"$ref":"#/components/schemas/CommitmentOfferComparisonTotals"}]},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination. Each entry's totals + delta_vs_current answer 'what's the portfolio-wide impact of this term?' in one place — no client-side summing across commitments required.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentTotal"}},"data":{"type":"array","description":"Per-commitment detail. Use when the user wants to drill into a specific commitment's alternatives.","items":{"$ref":"#/components/schemas/CommitmentOfferComparisonRow"}},"skipped_commitments":{"type":"array","description":"Commitments that couldn't be compared (e.g. no recent SKU usage). Surface to the user so the rollup scope is honest — these commitments contribute neither to current_totals nor to hypothetical_totals.","items":{"$ref":"#/components/schemas/SkippedCommitment"}}},"required":["current_totals","data","hypothetical_totals","skipped_commitments"],"additionalProperties":false},"CommitmentOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the commitments in scope. Same shape as on plans / line items. No-rebate basis to keep totals apples-to-apples with hypothetical_totals.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the commitments in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalCommitmentTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each commitment adopts its candidate per the fallback rule.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the commitments under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'how much did I leave on the table' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalCommitmentDelta"}]},"commitments":{"type":"array","description":"Per-commitment resolution for this hypothetical. Use to call out fallbacks ('14 of 20 commitments would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current') and underutilized-commitment caveats.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentEntry"}},"low_utilization_commitment_count":{"type":"integer","description":"Number of commitments in this rollup whose recent utilization is below 50%. Convenience aggregate of the per-row utilization_warning flags. Surface when non-zero: the rollup deltas may overstate the savings opportunity since underutilized commitments project candidate savings against hours that aren't actually consumed."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","commitments","contract_term","delta_vs_current","low_utilization_commitment_count","payment_option"],"additionalProperties":false},"HypotheticalCommitmentDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the portfolio does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"actual_term":{"description":"The contract term this commitment actually contributes to the rollup at. Equals the target when an exact match exists; otherwise the longest available term <= target with the same payment option, or the commitment's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this commitment contributes. Equals the target except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this commitment landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."},"utilization_warning":{"type":"boolean","description":"True if this commitment's recent utilization is below 50% — the comparison for it is less informative because candidates are sized from observed usage, not the commitment's nominal capacity. Surface to the user when present so the rollup is framed honestly."}},"required":["actual_payment_option","actual_term","actual_term_reason","commitment_id","utilization_warning"],"additionalProperties":false},"CommitmentOfferComparisonRow":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"current":{"description":"The existing commitment as the baseline — full identity, utilization, and current economics. Same shape as the singular tool's `current` block.","allOf":[{"$ref":"#/components/schemas/CurrentCommitmentEntry"}]},"candidates":{"type":"array","description":"Candidate offer alternatives sized for the same observed usage, filtered to the requested contract_terms and payment_options. Each candidate's delta_vs_current is per-COMMITMENT (NOT portfolio-wide). Sorted by net monthly savings, best first. May be empty when no valid replacements exist.","items":{"$ref":"#/components/schemas/CandidateOfferEntry_Exclude_IsCurrent"}}},"required":["candidates","commitment_id","current"],"additionalProperties":false},"CurrentCommitmentEntry":{"type":"object","properties":{"commitment":{"description":"Full identity of the existing commitment — id, provider, type, instance/region/account, dates, payment_option, contract_term, guarantee info. Same shape as `commitment_details`'s identity fields (no metrics).","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Cost-weighted utilization rate (0-1) over the recent observation period the comparison is built against. The grid sizes candidates from observed usage, so utilization context matters for framing — low utilization means candidates reflect alternatives sized for actual usage, not for the commitment's original capacity.","nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1), NET basis (`(gross - premium) / on-demand`) — apples-to-apples with candidates."},"breakeven_days":{"type":"number","description":"Days until the existing commitment paid for itself, computed from upfront_cost and hourly net savings. Null if net savings are not positive.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for the existing commitment in the no-rebate shape used by candidates. `commitment_savings.net` here is `gross - premium`, NOT including any rebate the commitment may be accruing — kept on the no-rebate basis so deltas vs candidates are apples-to-apples. For true current economics including rebate income, call `commitment_details`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"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."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CandidateOfferEntry_Exclude_IsCurrent":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false},"SkippedCommitment":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"reason":{"type":"string","description":"Why this commitment was skipped — typically 'no recent SKU usage' (commitment has no usage attributed to it in the recent observation window, so the candidate grid can't be built). Surface to the user rather than dropping silently."}},"required":["commitment_id","reason"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment portfolio metrics over time

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/metrics":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"search","description":"Text search across commitment fields","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — same shape as `/commitments`. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Date-dependent metric fields are 730-hour monthly rates evaluated over the requested `start_date` / `end_date` window: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window. Note that the RESPONSE on this endpoint reports period totals (`commitment_financials_period_total.*`), not monthly rates — so a filter like `{\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000}` selects commitments saving at >$1000/month rate during the window, even though the response will show the dollar total accumulated over the window itself.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment portfolio metrics over time","description":"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."}}},"components":{"schemas":{"MetricsResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"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_end":{"type":"string","description":"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)."},"utilization":{"type":"number","description":"Cost-weighted average utilization across the period (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Total cost of unused commitment capacity for the period"},"commitment_financials_period_total":{"description":"Sum of commitment economics aggregated across commitments over the requested date range. commitment_savings.rebate is the sum of per-commitment rebates for the period.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"data":{"type":"array","description":"Per-day data points for trend analysis","items":{"$ref":"#/components/schemas/DailyMetricsDataPoint"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"DailyMetricsDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date (YYYY-MM-DD)"},"utilization":{"type":"number","description":"Cost-weighted utilization rate for this day (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Cost of unused/underutilized commitment capacity for this day"},"commitment_financials_daily_total":{"description":"Sum of commitment economics aggregated across commitments for this day. commitment_savings.rebate is the sum of per-commitment rebates for this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archera.ai/api-reference/beta-api/commitments-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.