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

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

Sample Response

[
  {
    "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

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

{
  "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

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

{
  "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
    }
  ]
}