> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/cost-management-agent-apis/commitment-orchestrator/ri-inventory-apis.md).

# RI Inventory APIs

## List Reserved Instances

> Retrieves a paginated list of Reserved Instances with optional filtering

```json
{"openapi":"3.0.1","info":{"title":"Commitment Orchestrator APIs","version":"1.0.0"},"tags":[],"servers":[{"url":"https://app.harness.io/gateway","description":"Production server"}],"paths":{"/accounts/{account_id}/v2/inventory/ri/list":{"post":{"tags":["RI Inventory APIs"],"summary":"List Reserved Instances","description":"Retrieves a paginated list of Reserved Instances with optional filtering","operationId":"ListReservedInstances","parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"Account Identifier for the Entity"},{"name":"routingId","in":"query","required":true,"schema":{"type":"string"},"description":"Routing identifier for request processing"},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date for filtering Reserved Instances"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date for filtering Reserved Instances"}],"requestBody":{"description":"Pagination and filtering options","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListReservedInstancesRequest"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListReservedInstancesResponse"}}}},"400":{"description":"Invalid request parameters"}}}}},"components":{"schemas":{"ListReservedInstancesRequest":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/PaginationInput"},"filters":{"$ref":"#/components/schemas/InventoryRIAPIFilter"},"sort_by":{"type":"string","description":"Field to sort results by"},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Sort order direction"}}},"PaginationInput":{"type":"object","properties":{"limit":{"type":"integer","maximum":100},"page":{"type":"integer","maximum":100}}},"InventoryRIAPIFilter":{"type":"object","properties":{"account_ids":{"type":"array","items":{"type":"string"},"description":"List of provider account IDs"},"cloud_account_ids":{"type":"array","items":{"type":"string"},"description":"List of cloud account IDs"},"instance_types":{"type":"array","items":{"type":"string"},"description":"List of instance types"},"instance_families":{"type":"array","items":{"type":"string"},"description":"List of instance families"},"platforms":{"type":"array","items":{"type":"string"},"description":"List of platforms"},"tenancy":{"type":"array","items":{"type":"string"},"description":"List of tenancy options"},"payment_options":{"type":"array","items":{"type":"string","enum":["No Upfront","Partial Upfront","All Upfront"]},"description":"List of payment options"},"terms":{"type":"array","items":{"type":"number","format":"float64"},"description":"List of term lengths in years"},"plan_types":{"type":"array","items":{"type":"string","enum":["Standard","Convertible"]},"description":"List of RI types"},"status":{"type":"array","items":{"type":"string","enum":["active","expired","pending","retired"]},"description":"List of statuses"},"is_harness_managed":{"type":"boolean","nullable":true,"description":"Filter by Harness managed status"},"regions":{"type":"array","items":{"type":"string"},"description":"List of regions"},"service":{"type":"string","enum":["Amazon Relational Database Service","Amazon Elastic Compute Cloud - Compute","VirtualMachines"],"default":"Amazon Elastic Compute Cloud - Compute","description":"Service to fetch the inventory for. VirtualMachines returns Azure reservations, whose scope is the applied scope (Billing, Subscription or Management Group) instead of the region."}}},"ListReservedInstancesResponse":{"type":"object","properties":{"ts":{"type":"integer","description":"Response timestamp"},"success":{"type":"boolean","description":"Indicates if the request was successful"},"errors":{"type":"string","nullable":true,"description":"Error details, if any"},"response":{"$ref":"#/components/schemas/ReservedInstancesData"}}},"ReservedInstancesData":{"type":"object","properties":{"total":{"type":"integer","format":"int64","description":"Total number of Reserved Instances"},"pages":{"type":"integer","format":"int64","description":"Total number of pages"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReservedInstance"}},"pagination":{"$ref":"#/components/schemas/PaginationInput"}}},"ReservedInstance":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the Reserved Instance"},"type":{"type":"string","description":"Type of Reserved Instance (e.g., Convertible)"},"count":{"type":"integer","description":"Number of instances in this reservation"},"scope":{"type":"string","description":"Scope of the reservation. AWS returns the region; Azure returns the applied scope (Billing, Subscription or Management Group)"},"availability_zone":{"type":"string","description":"Availability zone if applicable"},"start_date":{"type":"string","format":"date-time","description":"Start date of the reservation"},"expires_on":{"type":"string","format":"date-time","description":"Expiration date of the reservation"},"term":{"type":"string","description":"Term length of the reservation"},"avg_utilization":{"type":"number","format":"float","description":"Average utilization percentage"},"status":{"type":"string","description":"Current status of the reservation"},"is_harness_managed":{"type":"boolean","description":"Indicates if the reservation is managed by Harness"},"is_seed_ri":{"type":"boolean","description":"Indicates if this is a seed reservation"}}}}}}
```

## Get Reserved Instance Details

> Retrieves detailed information about a specific Reserved Instance

```json
{"openapi":"3.0.1","info":{"title":"Commitment Orchestrator APIs","version":"1.0.0"},"tags":[],"servers":[{"url":"https://app.harness.io/gateway","description":"Production server"}],"paths":{"/accounts/{account_id}/v2/inventory/ri/{riId}/detail":{"get":{"tags":["RI Inventory APIs"],"summary":"Get Reserved Instance Details","description":"Retrieves detailed information about a specific Reserved Instance","operationId":"GetReservedInstanceDetails","parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"Account Identifier for the Entity"},{"name":"riId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of the Reserved Instance"},{"name":"routingId","in":"query","required":true,"schema":{"type":"string"},"description":"Routing identifier for request processing"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservedInstanceDetailsResponse"}}}},"400":{"description":"Invalid request parameters"},"404":{"description":"Reserved Instance not found"}}}}},"components":{"schemas":{"ReservedInstanceDetailsResponse":{"type":"object","properties":{"ts":{"type":"integer","description":"Response timestamp"},"success":{"type":"boolean","description":"Indicates if the request was successful"},"errors":{"type":"string","nullable":true,"description":"Error details, if any"},"response":{"$ref":"#/components/schemas/ReservedInstanceDetail"}}},"ReservedInstanceDetail":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the Reserved Instance"},"instance_type":{"type":"string","description":"Type of EC2 instance"},"scope":{"type":"string","description":"Scope of the reservation. AWS returns the region; Azure returns the applied scope (Billing, Subscription or Management Group)"},"instance_count":{"type":"integer","description":"Number of instances in this reservation"},"availability_zone":{"type":"string","description":"Availability zone if applicable"},"platform":{"type":"string","description":"Operating system platform"},"tenancy":{"type":"string","description":"Instance tenancy (e.g., Shared, Dedicated)"},"type":{"type":"string","description":"Type of Reserved Instance (e.g., Convertible)"},"utilization":{"type":"number","format":"float","description":"Current utilization percentage"},"status":{"type":"string","description":"Current status of the reservation"},"start_date":{"type":"string","format":"date-time","description":"Start date of the reservation"},"expiry_date":{"type":"string","format":"date-time","description":"Expiration date of the reservation"},"purchase_term_years":{"type":"string","description":"Term length of the reservation"},"payment_option":{"type":"string","description":"Payment option selected"},"upfront_fee":{"type":"number","format":"double","description":"Upfront payment amount"},"usage_price":{"type":"number","format":"double","description":"Usage price per hour"},"hourly_cost":{"type":"number","format":"double","description":"Total hourly cost"},"purchase_date":{"type":"string","format":"date-time","description":"Date when the reservation was purchased"},"previously_was":{"$ref":"#/components/schemas/PreviousStateInfo"},"approval_info":{"$ref":"#/components/schemas/ApprovalInfo"},"is_harness_managed":{"type":"boolean","description":"Indicates if the reservation is managed by Harness"}}},"PreviousStateInfo":{"type":"object","properties":{"instance_type":{"type":"string","description":"Previous instance type"},"platform":{"type":"string","description":"Previous platform"},"tenancy":{"type":"string","description":"Previous tenancy"}}},"ApprovalInfo":{"type":"object","properties":{"approved_by":{"type":"string","description":"User who approved the change"},"approved_at":{"type":"string","format":"date-time","description":"Timestamp of approval"},"status":{"type":"string","description":"Current approval status"}}}}}}
```

## Get Reserved Instance Filter Options

> Retrieves available filter options for Reserved Instances including account IDs, instance types, platforms, etc.

```json
{"openapi":"3.0.1","info":{"title":"Commitment Orchestrator APIs","version":"1.0.0"},"tags":[],"servers":[{"url":"https://app.harness.io/gateway","description":"Production server"}],"paths":{"/accounts/{account_id}/v2/filters/ri":{"get":{"tags":["RI Inventory APIs"],"summary":"Get Reserved Instance Filter Options","description":"Retrieves available filter options for Reserved Instances including account IDs, instance types, platforms, etc.","operationId":"GetRIFilterOptions","parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"Account Identifier for the Entity"},{"name":"routingId","in":"query","required":true,"schema":{"type":"string"},"description":"Routing identifier for request processing"},{"name":"service","in":"query","required":false,"schema":{"type":"string","enum":["Amazon Relational Database Service","Amazon Elastic Compute Cloud - Compute","VirtualMachines"]},"description":"Service to fetch filters for. VirtualMachines returns Azure reservation filters, which include instance families (VM series) but no RI types or tenancy."}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"ts":{"type":"integer","description":"Response timestamp"},"success":{"type":"boolean","description":"Indicates if the request was successful"},"errors":{"type":"string","nullable":true,"description":"Error details, if any"},"response":{"$ref":"#/components/schemas/InventoryRIAPIFilter"}}}}}},"400":{"description":"Invalid request parameters"}}}}},"components":{"schemas":{"InventoryRIAPIFilter":{"type":"object","properties":{"account_ids":{"type":"array","items":{"type":"string"},"description":"List of provider account IDs"},"cloud_account_ids":{"type":"array","items":{"type":"string"},"description":"List of cloud account IDs"},"instance_types":{"type":"array","items":{"type":"string"},"description":"List of instance types"},"instance_families":{"type":"array","items":{"type":"string"},"description":"List of instance families"},"platforms":{"type":"array","items":{"type":"string"},"description":"List of platforms"},"tenancy":{"type":"array","items":{"type":"string"},"description":"List of tenancy options"},"payment_options":{"type":"array","items":{"type":"string","enum":["No Upfront","Partial Upfront","All Upfront"]},"description":"List of payment options"},"terms":{"type":"array","items":{"type":"number","format":"float64"},"description":"List of term lengths in years"},"plan_types":{"type":"array","items":{"type":"string","enum":["Standard","Convertible"]},"description":"List of RI types"},"status":{"type":"array","items":{"type":"string","enum":["active","expired","pending","retired"]},"description":"List of statuses"},"is_harness_managed":{"type":"boolean","nullable":true,"description":"Filter by Harness managed status"},"regions":{"type":"array","items":{"type":"string"},"description":"List of regions"},"service":{"type":"string","enum":["Amazon Relational Database Service","Amazon Elastic Compute Cloud - Compute","VirtualMachines"],"default":"Amazon Elastic Compute Cloud - Compute","description":"Service to fetch the inventory for. VirtualMachines returns Azure reservations, whose scope is the applied scope (Billing, Subscription or Management Group) instead of the region."}}}}}}
```
