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

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_idstring · min: 1Required

Query parameters

searchstringOptional

Text to search across multiple columns (case-insensitive partial match)

Example: us-east-1

filterobject · nullableOptional

JSON object specifying field-specific filter criteria

Example: {"field": "type", "op": "=", "value": "Standard"}

descbooleanOptional

Sort in descending order if true

Default: trueExample: true

order_bystring,null · enum · nullableOptional

Field to order results by

Default: end_dateExample: created_atPossible values:

providerstring · enumRequired

Cloud provider to filter commitments by

Example: awsPossible values:

start_datestring · dateRequired

Start date for the commitment period (YYYY-MM-DD)

Example: 2023-01-01

end_datestring · dateRequired

End date for the commitment period (YYYY-MM-DD)

Example: 2023-12-31

pageinteger · min: 1OptionalDefault: 1

page_sizeinteger · min: 1 · max: 10000OptionalDefault: 10

Responses

200

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

get/v1/org/{org_id}/commitments

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

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

get

Path parameters

org_idstring · min: 1Required

Query parameters

searchstringOptional

Text to search across multiple columns (case-insensitive partial match)

Example: us-east-1

filterobject · nullableOptional

JSON object specifying field-specific filter criteria

Example: {"field": "type", "op": "=", "value": "Standard"}

descbooleanOptional

Sort in descending order if true

Default: trueExample: true

order_bystring,null · enum · nullableOptional

Field to order results by

Default: end_dateExample: created_atPossible values:

providerstring · enumRequired

Cloud provider to filter commitments by

Example: awsPossible values:

start_datestring · dateRequired

Start date for the commitment period (YYYY-MM-DD)

Example: 2023-01-01

end_datestring · dateRequired

End date for the commitment period (YYYY-MM-DD)

Example: 2023-12-31

Responses

200

application/json

idsstring[]Required

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

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

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

{
  "ids": [
    "text"
  ]
}

/commitments/chart

get

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.

Path parameters

org_idstring · min: 1Required

Query parameters

filterobject · nullableOptional

Optional JSON filter criteria for commitment data

Example: {"field": "type", "op": "=", "value": "Compute Instance"}

providerstring · enumRequired

Cloud provider to filter commitments by

Example: awsPossible values:

start_datestring · dateRequired

Start date for the chart data (YYYY-MM-DD)

Example: 2023-01-01

end_datestring · dateRequired

End date for the chart data (YYYY-MM-DD)

Example: 2023-12-31

Responses

200

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

get/v1/org/{org_id}/commitments/chart

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

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

PreviousCommitment Plans NextExchanges

Last updated 3 days ago

Was this helpful?