# Commitments

API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information.

## /commitments

> Retrieves a paginated list of commitments for the specified organization and time period. Returns detailed information about each commitment including utilization, savings, and status. Results can be filtered by provider, search term, and custom criteria, and sorted by various attributes.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitments","description":"API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information."}],"paths":{"/v1/org/{org_id}/commitments":{"get":{"parameters":[{"in":"query","name":"search","description":"Text to search across multiple columns (case-insensitive partial match)","schema":{"type":"string"},"required":false},{"in":"query","name":"filter","description":"JSON object specifying field-specific filter criteria","schema":{"type":["object","null"],"additionalProperties":{}},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"end_date","enum":["duration_seconds","start_date","end_date","upfront_cost","amortized_cost","recurring_cost","created_at","updated_at","is_leased","account_id","type","status","scope","reservation_end","utilization","monthly_savings",null]},"required":false},{"in":"query","name":"provider","description":"Cloud provider to filter commitments by","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"start_date","description":"Start date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":10,"minimum":1,"maximum":10000},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCommitment"}}}},"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"],"summary":"/commitments","description":"Retrieves a paginated list of commitments for the specified organization and time period. Returns detailed information about each commitment including utilization, savings, and status. Results can be filtered by provider, search term, and custom criteria, and sorted by various attributes."}}},"components":{"schemas":{"PublicCommitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"display_name":{"type":"string"},"leased_display_name":{"type":"string"},"provider_reservation_id":{"type":"string"},"account_id":{"type":["string","null"]},"master_account_id":{"readOnly":true,"deprecated":true,"type":["string","null"]},"billing_account_id":{"type":["string","null"]},"type":{"type":"string"},"region":{"type":["string","null"]},"duration_seconds":{"type":["integer","null"]},"reservation_end":{"type":["string","null"]},"reservation_start":{"type":["string","null"]},"transfer_reservation_start":{"type":["string","null"],"format":"date-time"},"transfer_reservation_end":{"type":["string","null"],"format":"date-time"},"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"status":{"enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_leased":{"type":"boolean"},"is_active":{"type":"boolean"},"lease":{"anyOf":[{"$ref":"#/components/schemas/LeaseMenuItem"},{"type":"null"}]},"lease_start":{"type":["string","null"],"format":"date-time"},"lease_lockin_date":{"type":["string","null"],"format":"date-time"},"upfront_cost":{"type":"number"},"recurring_cost":{"type":"number"},"is_flexible":{"type":["boolean","null"]},"payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"offering_class":{"enum":["standard","convertible",null]},"offering_id":{"type":["string","null"]},"instance_count":{"type":["integer","null"]},"effective_instance_count":{"type":["integer","null"]},"product_description":{"type":["string","null"]},"instance_family":{"type":["string","null"]},"instance_type":{"type":["string","null"]},"tenancy":{"type":["string","null"]},"az":{"type":["string","null"]},"is_multi_az":{"type":["boolean","null"]},"plan_type":{"type":["string","null"]},"scope":{"enum":["shared","subscription","resource_group","management_group",null]},"name":{"type":["string","null"]},"order_id":{"type":["string","null"]},"resource_group":{"type":["string","null"]},"instance_flexibility":{"type":["boolean","null"]},"savings":{"type":["number","null"]},"monthly_savings":{"type":["number","null"]},"net_savings":{"type":["number","null"]},"utilization":{"type":["number","null"]},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"amortized_cost":{"type":["number","null"]},"daily_utilizations":{"type":"array","items":{"$ref":"#/components/schemas/DailyUtilization"}}},"required":["account_id","amortized_cost","az","billing_account_id","daily_utilizations","display_name","duration_seconds","effective_instance_count","end_date","id","instance_count","instance_family","instance_flexibility","instance_type","is_active","is_flexible","is_leased","is_multi_az","lease","lease_lockin_date","lease_start","leased_display_name","master_account_id","monthly_savings","name","net_savings","offering_class","offering_id","order_id","payment_option","plan_type","potential_savings","product_description","provider","provider_reservation_id","recurring_cost","region","reservation_end","reservation_start","resource_group","running_hours","savings","scope","start_date","status","tenancy","transfer_reservation_end","transfer_reservation_start","type","upfront_cost","utilization"],"additionalProperties":false},"LeaseMenuItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fee_type":{"type":"string"},"fee_rate":{"type":"number"},"is_rebate":{"type":"boolean"},"lockin_months":{"type":"integer"},"term_months":{"type":"integer"}},"required":["fee_rate","fee_type","is_rebate","lockin_months","term_months"],"additionalProperties":false},"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date"},"reservation_utilization":{"type":"number"},"covered_cost":{"type":"number"},"cost":{"type":"number"},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"savings":{"type":"number"},"unutilized_commit":{"type":"number"},"gri_fees":{"type":"number"},"net_savings":{"type":"number"}},"required":["cost","covered_cost","date","gri_fees","net_savings","potential_savings","reservation_utilization","running_hours","savings","unutilized_commit"],"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":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"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 /v1/org/{org\_id}/commitments/ids

>

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitments","description":"API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information."}],"paths":{"/v1/org/{org_id}/commitments/ids":{"get":{"parameters":[{"in":"query","name":"search","description":"Text to search across multiple columns (case-insensitive partial match)","schema":{"type":"string"},"required":false},{"in":"query","name":"filter","description":"JSON object specifying field-specific filter criteria","schema":{"type":["object","null"],"additionalProperties":{}},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"end_date","enum":["duration_seconds","start_date","end_date","upfront_cost","amortized_cost","recurring_cost","created_at","updated_at","is_leased","account_id","type","status","scope","reservation_end","utilization","monthly_savings",null]},"required":false},{"in":"query","name":"provider","description":"Cloud provider to filter commitments by","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"start_date","description":"Start date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdsResponse"}}}},"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"]}}},"components":{"schemas":{"IdsResponse":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"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"}}}}}}}
```

## /commitments/chart

> Generates time-series chart data for commitment metrics over the specified time period. The data includes daily or monthly values for commitment spend, utilization, locked vs unlocked commitments, and realized savings. Results are aggregated by day or month depending on the date range selected. \
> \
> \*\*Future Projections:\*\* When the end\_date extends into the future, the API returns projected values based on current commitment utilization patterns. Each data point includes an \`is\_projection\` field that indicates whether the values are historical (false) or projected (true). Projected values assume that active commitments will continue with their current utilization rates through their expiration dates. This is useful for forecasting future commitment costs and savings based on existing commitments.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitments","description":"API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information."}],"paths":{"/v1/org/{org_id}/commitments/chart":{"get":{"parameters":[{"in":"query","name":"filter","description":"Optional JSON filter criteria for commitment data","schema":{"type":["object","null"],"additionalProperties":{}},"required":false},{"in":"query","name":"provider","description":"Cloud provider to filter commitments by","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"required":true},{"in":"query","name":"start_date","description":"Start date for the chart data (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the chart data (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubChartResponse"}}}},"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"],"summary":"/commitments/chart","description":"Generates time-series chart data for commitment metrics over the specified time period. The data includes daily or monthly values for commitment spend, utilization, locked vs unlocked commitments, and realized savings. Results are aggregated by day or month depending on the date range selected. \n\n**Future Projections:** When the end_date extends into the future, the API returns projected values based on current commitment utilization patterns. Each data point includes an `is_projection` field that indicates whether the values are historical (false) or projected (true). Projected values assume that active commitments will continue with their current utilization rates through their expiration dates. This is useful for forecasting future commitment costs and savings based on existing commitments."}}},"components":{"schemas":{"PubChartResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataPoint"}}},"additionalProperties":false},"DataPoint":{"type":"object","properties":{"date":{"type":"string"},"remaining_commit":{"type":"number"},"locked_commit":{"type":"number"},"unlocked_commit":{"type":"number"},"savings":{"type":"number"},"net_savings":{"type":"number"},"utilization":{"type":"number"},"unutilized_commit":{"type":"number"},"is_projection":{"type":"boolean","description":"Indicates whether this data point is a projection based on current commitment utilization patterns. Historical data (is_projection=false) reflects actual recorded metrics, while projected data (is_projection=true) represents estimated future values assuming commitments continue with their current utilization rates."}},"required":["date","is_projection","locked_commit","net_savings","remaining_commit","savings","unlocked_commit","unutilized_commit","utilization"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"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"}}}}}}}
```