# API for 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

### `get/v1/org/{org_id}/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.

### Path parameters

- **org_id** `string` · min: 1 Required

### Query parameters

- **search** `string` Optional  
  Text to search across multiple columns (case-insensitive partial match)  
  Example: `us-east-1`
- **filter** `object` · nullable Optional  
  JSON object specifying field-specific filter criteria  
  Example: `{"field": "type", "op": "=", "value": "Standard"}`
- **desc** `boolean` Optional  
  Sort in descending order if true  
  Default: `true`  Example: `true`
- **order_by** `string,null` · enum · nullable Optional  
  Field to order results by  
  Default: `end_date`  Example: `created_at`  Possible values: `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`
- **provider** `string` · enum Required  
  Cloud provider to filter commitments by  
  Example: `aws`  Possible values: `aws`, `azure`, `gcp`
- **start_date** `string` · date Required  
  Start date for the commitment period (YYYY-MM-DD)  
  Example: `2023-01-01`
- **end_date** `string` · date Required  
  End date for the commitment period (YYYY-MM-DD)  
  Example: `2023-12-31`
- **page** `integer` · min: 1 Optional  
  Default: `1`
- **page_size** `integer` · min: 1 · max: 10,000 Optional  
  Default: `10`

### Responses

- **200 OK**  
  Headers: `object`  
  Response: `PublicCommitment[]`
- **400 Bad request**  
  Content-Type: `application/json`
- **401 Unauthorized**  
  Content-Type: `application/json`
- **403 Forbidden**  
  Content-Type: `application/json`
- **404 Not found**  
  Content-Type: `application/json`
- **405 Method not allowed**  
  Content-Type: `application/json`
- **409 Conflict**  
  Content-Type: `application/json`
- **422 Unprocessable Content**  
  Content-Type: `application/json`
- **500 Internal server error**  
  Content-Type: `application/json`
- **default**  
  Default error response  
  Content-Type: `application/json`

### Example

```http
GET /v1/org/{org_id}/commitments?provider=aws&start_date=2023-01-01&end_date=2023-12-31 HTTP/1.1
Accept: */*
```

#### Sample Response

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "aws",
    "display_name": "text",
    "leased_display_name": "text",
    "provider_reservation_id": "text",
    "account_id": null,
    "billing_account_id": null,
    "type": "text",
    "region": null,
    "duration_seconds": null,
    "reservation_end": null,
    "reservation_start": null,
    "transfer_reservation_start": null,
    "transfer_reservation_end": null,
    "start_date": null,
    "end_date": null,
    "status": "active",
    "is_leased": true,
    "is_active": true,
    "lease": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "fee_type": "text",
      "fee_rate": 1,
      "is_rebate": true,
      "lockin_months": 1,
      "term_months": 1
    },
    "lease_start": null,
    "lease_lockin_date": null,
    "upfront_cost": 1,
    "recurring_cost": 1,
    "is_flexible": null,
    "payment_option": "No Upfront",
    "offering_class": "standard",
    "offering_id": null,
    "instance_count": null,
    "effective_instance_count": null,
    "product_description": null,
    "instance_family": null,
    "instance_type": null,
    "tenancy": null,
    "az": null,
    "is_multi_az": null,
    "plan_type": null,
    "scope": "shared",
    "name": null,
    "order_id": null,
    "resource_group": null,
    "instance_flexibility": null,
    "savings": null,
    "monthly_savings": null,
    "net_savings": null,
    "utilization": null,
    "potential_savings": null,
    "running_hours": null,
    "amortized_cost": null,
    "daily_utilizations": [
      {
        "date": "2026-07-27",
        "reservation_utilization": 1,
        "covered_cost": 1,
        "cost": 1,
        "potential_savings": null,
        "running_hours": null,
        "savings": 1,
        "unutilized_commit": 1,
        "gri_fees": 1,
        "net_savings": 1
      }
    ]
  }
]
```

## /commitments/ids

### `get/v1/org/{org_id}/commitments/ids`

### Path parameters

- **org_id** `string` · min: 1 Required

### Query parameters

- **search** `string` Optional  
  Example: `us-east-1`
- **filter** `object` · nullable Optional  
  Example: `{"field": "type", "op": "=", "value": "Standard"}`
- **desc** `boolean` Optional  
  Default: `true`
- **order_by** `string,null` · enum · nullable Optional  
  Default: `end_date`
- **provider** `string` · enum Required  
  Example: `aws`
- **start_date** `string` · date Required  
  Example: `2023-01-01`
- **end_date** `string` · date Required  
  Example: `2023-12-31`

### Responses

- **200 OK**  
  Response: `ids string[]`  
- **Other responses** common as above

### Example

```http
GET /v1/org/{org_id}/commitments/ids?provider=aws&start_date=2023-01-01&end_date=2023-12-31 HTTP/1.1
Accept: */*
```

#### Sample Response

```json
{
  "ids": [
    "text"
  ]
}
```

## /commitments/chart

### `get/v1/org/{org_id}/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.

### Path parameters

- **org_id** `string` · min: 1 Required

### Query parameters

- **filter** `object` · nullable Optional  
  Example: `{"field": "type", "op": "=", "value": "Compute Instance"}`
- **provider** `string` · enum Required  
  Example: `aws`
- **start_date** `string` · date Required  
  Example: `2023-01-01`
- **end_date** `string` · date Required  
  Example: `2023-12-31`

### Responses

- **200 OK**  
  Data: `object` · DataPoint[] Optional  
- **Other responses** common as above

### Example

```http
GET /v1/org/{org_id}/commitments/chart?provider=aws&start_date=2023-01-01&end_date=2023-12-31 HTTP/1.1
Accept: */*
```

#### Sample Response

```json
{
  "data": [
    {
      "date": "text",
      "remaining_commit": 1,
      "locked_commit": 1,
      "unlocked_commit": 1,
      "savings": 1,
      "net_savings": 1,
      "utilization": 1,
      "unutilized_commit": 1,
      "is_projection": true
    }
  ]
}
```