Commitment Plans (Beta) | API & MCP Reference | Archera
For the complete documentation index, see llms.txt. This page is also available as Markdown.
GitBook AssistantAsk
On this page
Agent-friendly commitment plan endpoints
GitBook Assistant
List commitment plansDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans
Returns commitment plans scoped to one segment for the given provider. segment_id defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees the plans tied to their default segment without cross-segment duplicates. Further filters (template, status, flags) narrow within that scope. Coverage metrics (current_coverage / projected_coverage) are omitted here for speed; fetch the detail endpoint for those.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Example: awsPossible values: aws``azure``gcp
segment_idstring · uuid · nullableOptional
Optional segment ID to scope results. Defaults to the provider resources segment if not specified.
Default: null
template_idstring · uuid · nullableOptional
Filter to plans generated from this template (GET /commitment-plan-templates)
Default: null
statusstring · enum · nullableOptional
Filter by plan status (e.g. 'draft', 'in_progress')
Default: nullPossible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress``null
is_recommendedboolean · nullableOptional
Filter to the flagged recommended plan
Default: null
is_system_generatedboolean · nullableOptional
Filter to system-generated (default) plans — the three built-ins (Recommended / Balanced / High Savings) vs. user-created plans.
Default: null
is_renewalboolean · nullableOptional
Switch which flavor the list returns. Omitted (default) and false both return segment-scoped non-renewal plans — backward-compatible with the pre-renewal contract. Set to true to fetch renewal plans (which aren't segment-scoped — segment_id is ignored). There's no combined view; renewals and non-renewals are queried separately.
Default: null
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
True if this plan was created to renew a set of expiring commitments — configuration.renewal_commitment_ids is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments).
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero.
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
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/beta/v1/org/{org_id}/commitment-plans
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans?provider=aws HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
[\
{\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"provider": "aws",\
"name": "text",\
"description": "text",\
"is_renewal": true,\
"status": "new",\
"is_calculating": true,\
"created_at": "2026-07-27T19:35:56.493Z",\
"usage_start_date": "2026-07-27T19:35:56.493Z",\
"usage_end_date": "2026-07-27T19:35:56.493Z",\
"max_term": "text",\
"minimum_commitment": 1,\
"breakeven_days": null,\
"commitment_upfront_cost": 1,\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
},\
"configuration": {\
"max_upfront_cost": 0,\
"lookback_days": 1,\
"contract_specs": [\
{\
"commitment_type": "text",\
"contract_term": "one_year_gris",\
"payment_option": "no_upfront"\
}\
],\
"resource_ids": [],\
"renewal_commitment_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
]\
}\
}\
]
Create a commitment planDirect link to heading
post/beta/v1/org/{org_id}/commitment-plans
Creates a new commitment plan for the given segment. The plan is generated asynchronously; the response echoes the initial plan with is_calculating=true and omits coverage fields (meaningless mid-recalc). Poll GET /commitment-plans/{plan_id} once is_calculating=false to get the full detail including coverage and per-service breakdowns.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
Body
application/json
application/json
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Example: awsPossible values: aws``azure``gcp
segment_idstring · uuid · nullableOptional
Optional segment ID to scope results. Defaults to the provider resources segment if not specified.
Default: null
namestringRequired
Human-readable plan name
configurationobject · CommitmentPlanConfigurationRequired
Show properties
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
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
post/beta/v1/org/{org_id}/commitment-plans
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
POST /beta/v1/org/{org_id}/commitment-plans HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 333
{
"provider": "aws",
"segment_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"configuration": {
"max_upfront_cost": 0,
"lookback_days": 1,
"contract_specs": [\
{\
"commitment_type": "text",\
"contract_term": "one_year_gris",\
"payment_option": "no_upfront"\
}\
],
"resource_ids": [],
"renewal_commitment_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
]
}
}
200
OK
GitBook AssistantAskCopy
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "aws",
"name": "text",
"description": "text",
"is_renewal": true,
"status": "new",
"is_calculating": true,
"created_at": "2026-07-27T19:35:56.493Z",
"usage_start_date": "2026-07-27T19:35:56.493Z",
"usage_end_date": "2026-07-27T19:35:56.493Z",
"max_term": "text",
"minimum_commitment": 1,
"breakeven_days": null,
"commitment_upfront_cost": 1,
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
},
"configuration": {
"max_upfront_cost": 0,
"lookback_days": 1,
"contract_specs": [\
{\
"commitment_type": "text",\
"contract_term": "one_year_gris",\
"payment_option": "no_upfront"\
}\
],
"resource_ids": [],
"renewal_commitment_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
]
}
}
Create a renewal commitment planDirect link to heading
post/beta/v1/org/{org_id}/commitment-plans/renewals
Creates a new commitment plan that renews a set of expiring commitments. The plan covers the same resources the source commitments were covering, with the contract specs supplied in configuration driving the renewal recommendation. The plan is generated asynchronously — the response echoes the initial plan with is_calculating=true; poll GET /commitment-plans/{plan_id} until that flips to see the generated line items.
GitBook Assistant
Renewal plans always sit on the provider-resources segment; segment_id is not accepted. The usage window the recommender feeds on is derived automatically from the source commitments' end dates, so configuration.lookback_days is omitted (the field is rejected if sent). configuration.resource_ids is also rejected — configuration.renewal_commitment_ids carries the scope for a renewal plan, parallel to how configuration.resource_ids scopes an infrastructure plan on the regular create endpoint.
GitBook Assistant
Each generated line item carries a renewal_commitment_id linking it back to the source commitment it is proposed to replace. Pair with GET /commitment-plans/{plan_id}/renewal-commitments to see the source commitments side-by-side.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
Body
application/json
application/json
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Example: awsPossible values: aws``azure``gcp
namestringRequired
Human-readable plan name
configurationobject · RenewalCommitmentPlanConfigurationRequired
Show properties
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
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
post/beta/v1/org/{org_id}/commitment-plans/renewals
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
POST /beta/v1/org/{org_id}/commitment-plans/renewals HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 245
{
"provider": "aws",
"name": "text",
"configuration": {
"max_upfront_cost": 0,
"contract_specs": [\
{\
"commitment_type": "text",\
"contract_term": "one_year_gris",\
"payment_option": "no_upfront"\
}\
],
"renewal_commitment_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
]
}
}
200
OK
GitBook AssistantAskCopy
Get default commitment plansDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/default
Returns the three default Archera commitment plans: Recommended (30-day), Balanced (1-year), and High Savings (3-year).
GitBook Assistant
Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Example: awsPossible values: aws``azure``gcp
segment_idstring · uuid · nullableOptional
Optional segment ID to scope results. Defaults to the provider resources segment if not specified.
Default: null
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
current_coveragenumberRequired
Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.
projected_coveragenumberRequired
Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan.
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/beta/v1/org/{org_id}/commitment-plans/default
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/default?provider=aws HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
Get recommended commitment planDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/recommended
Returns the single recommended commitment plan for the organization. This is typically the 30-day Recommended plan. Returns 204 if no plan is available.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Example: awsPossible values: aws``azure``gcp
segment_idstring · uuid · nullableOptional
Optional segment ID to scope results. Defaults to the provider resources segment if not specified.
Default: null
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
current_coveragenumberRequired
Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.
projected_coveragenumberRequired
Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan.
204
No Content
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/beta/v1/org/{org_id}/commitment-plans/recommended
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/recommended?provider=aws HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
Get commitment plan detailsDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}
Returns details for a specific commitment plan by ID, including per-service breakdowns.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
current_coveragenumberRequired
Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.
projected_coveragenumberRequired
Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan.
covered_servicesobject · CoveredService[]Optional
List of cloud services covered by this plan, with per-service savings and commitment breakdowns
Show properties
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
405
Method not allowed
application/json
409
Conflict
application/json
500
Internal server error
application/json
default
Default error response
application/json
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
Update a commitment planDirect link to heading
put/beta/v1/org/{org_id}/commitment-plans/{plan_id}
Update the plan's name and/or configuration. Replacing configuration triggers a recalculation — the response will have is_calculating=true and line-item financials are invalid until generation completes. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Body
application/json
application/json
namestringOptional
New plan name
configurationobject · CommitmentPlanConfigurationOptional
Show properties
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
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
put/beta/v1/org/{org_id}/commitment-plans/{plan_id}
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
PUT /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 264
{
"name": "text",
"configuration": {
"max_upfront_cost": 0,
"lookback_days": 1,
"contract_specs": [\
{\
"commitment_type": "text",\
"contract_term": "one_year_gris",\
"payment_option": "no_upfront"\
}\
],
"resource_ids": [],
"renewal_commitment_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
]
}
}
200
OK
GitBook AssistantAskCopy
Delete a commitment planDirect link to heading
delete/beta/v1/org/{org_id}/commitment-plans/{plan_id}
Delete a commitment plan. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. Irreversible.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Responses
204
No Content
No content
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
405
Method not allowed
application/json
409
Conflict
application/json
500
Internal server error
application/json
default
Default error response
application/json
delete/beta/v1/org/{org_id}/commitment-plans/{plan_id}
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
DELETE /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1
Accept: */*
204
No Content
No content
Apply (purchase) a commitment planDirect link to heading
post/beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply
Executes the plan's selected line items as actual commitment purchases. Marks the plan as edited and records the initiating user. The plan is then processed by the commitment-purchase workflow — inspect the plan status afterwards for progress. Rejected if the plan is currently calculating or already locked.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
current_coveragenumberRequired
Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.
projected_coveragenumberRequired
Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan.
covered_servicesobject · CoveredService[]Optional
List of cloud services covered by this plan, with per-service savings and commitment breakdowns
Show properties
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
405
Method not allowed
application/json
409
Conflict
application/json
500
Internal server error
application/json
default
Default error response
application/json
post/beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
Copy a commitment plan, optionally applying line-item editsDirect link to heading
post/beta/v1/org/{org_id}/commitment-plans/{plan_id}/copy
Creates a draft copy of an existing commitment plan, including its line items and resource matches. The copy is a regular user-created plan (is_default=false, is_recommended=false) and is editable via PUT /commitment-plans/{plan_id}. Useful for forking a system-generated default plan (Recommended / Balanced / High Savings) so it can be modified — defaults themselves are read-only. The copy inherits the source plan's already-computed line items and financials, so it is ready immediately (is_calculating=false).
GitBook Assistant
Optionally apply line-item edits during the copy via two mutually exclusive modes:
GitBook Assistant
- Explicit: pass
line_item_updatesreferencing the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically.
GitBook Assistant
- Resolution: pass
target_contract_term(+ optionaltarget_payment_option/target_line_item_ids) and the server swaps every selected (or scoped) line item on the copy to the closest candidate at or below the target term. Saves the LLM having to enumerate per-line edits when the user wants a uniform shape change on the new plan.
GitBook Assistant
If any edit fails (unknown source line_item_id, invalid offer, integer-coercion error on a unit-basis offer's selected_amount, duplicate line_item_id within line_item_updates), the entire copy + updates rolls back — no orphan copy persists. This is the canonical 'copy to edit' workflow; saves the round trip and ID-translation logic vs a separate copy + update sequence.
GitBook Assistant
Returns the new plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the copy. Follow up with commitment_plan_details on the returned id if you need the full breakdown. In resolution mode the response additionally carries a resolution array with one entry per scoped line item (actual_term / actual_payment_option / actual_term_reason of exact_match, fallback_closest_shorter, or no_alternative). Surface no_alternative outcomes to the user so they understand why coverage may be partial.
GitBook Assistant
Rejected if the source plan is currently being calculated.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Body
application/json
application/json
target_contract_termstring · enum · nullableOptional
Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates — pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.
Default: nullPossible values: one_year_gris``thirty_day_gris``two_month_gris``three_month_gris``four_month_gris``five_month_gris``six_month_gris``seven_month_gris``eight_month_gris``nine_month_gris``ten_month_gris``eleven_month_gris``twelve_month_gris``thirteen_month_gris``fourteen_month_gris``fifteen_month_gris``sixteen_month_gris``seventeen_month_gris``eighteen_month_gris``nineteen_month_gris``twenty_month_gris``twenty_one_month_gris``twenty_two_month_gris``twenty_three_month_gris``twenty_four_month_gris``twenty_five_month_gris``twenty_six_month_gris``twenty_seven_month_gris``twenty_eight_month_gris``twenty_nine_month_gris``thirty_month_gris``thirty_one_month_gris``thirty_two_month_gris``thirty_three_month_gris``thirty_four_month_gris``thirty_five_month_gris``one_year``two_year``three_year``five_year``zero_day``thirty_day``two_month``three_month``four_month``five_month``six_month``seven_month``eight_month``nine_month``ten_month``eleven_month``thirteen_month``fourteen_month``fifteen_month``sixteen_month``seventeen_month``eighteen_month``nineteen_month``twenty_month``twenty_one_month``twenty_two_month``twenty_three_month``twenty_five_month``twenty_six_month``twenty_seven_month``twenty_eight_month``twenty_nine_month``thirty_month``thirty_one_month``thirty_two_month``thirty_three_month``thirty_four_month``thirty_five_month``null
target_payment_optionstring · enumOptional
Target payment option for resolution mode. Defaults to no_upfront — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when target_contract_term is null.
Default: no_upfrontPossible values: no_upfront``partial_upfront``all_upfront
target_line_item_idsstring · uuid[] · nullableOptional
Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when target_contract_term is null.
Default: null
namestring · nullableOptional
Name for the copied plan. If omitted, defaults to ' <today's date>'.
Default: null
line_item_updatesobject · LineItemUpdateEntry[] · nullableOptional
Optional list of line-item edits to apply during the copy. Each entry has the same shape as update_commitment_plan_line_items's updates (line_item_id + optional is_selected / account_id / offer-swap triple). Entries reference the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically. If any edit fails, the entire copy + updates rolls back. Use this for the canonical 'copy to edit' workflow — saves the round trip and ID-translation logic that would otherwise live on the client. Mutually exclusive with target_contract_term (resolution mode).
Default: null
Show properties
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
resolutionobject · HypotheticalLineItem[] · nullableOptional
Per-line-item resolution outcome when target_contract_term was passed. One entry per line item that was IN SCOPE for the request (covers no_alternative items too — those are not in the applied updates but are surfaced here so callers can see what the server couldn't satisfy). actual_term_reason is one of: exact_match (landed at target), fallback_closest_shorter (used the longest available term ≤ target with same payment option), no_alternative (no candidate satisfied — line item left unchanged). Absent / null on explicit-mode calls.
Show properties
400
Bad Request
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
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
post/beta/v1/org/{org_id}/commitment-plans/{plan_id}/copy
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/copy HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 402
{
"target_contract_term": "one_year_gris",
"target_payment_option": "no_upfront",
"target_line_item_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
],
"name": "text",
"line_item_updates": [\
{\
"line_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"is_selected": true,\
"account_id": "text",\
"offer_id": "123e4567-e89b-12d3-a456-426614174000",\
"lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"selected_amount": 1\
}\
]
}
200
OK
GitBook AssistantAskCopy
Get commitment plan line itemsDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items
Returns individual commitment recommendations within a plan, including offer details, per-line-item savings, and costs. Each line item has an is_selected field: if false, the line item is excluded from the plan and its costs/savings are NOT included in the plan's top-level metrics. Pass line_item_ids to fetch a specific subset (e.g. a single line item).
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Query parameters
line_item_idsstring · uuid[] · nullableOptional
Optional list of line-item ids to scope the response to. When omitted, returns every line item in the plan.
Default: null
renewal_commitment_idsstring · uuid[] · nullableOptional
Renewal plans only: scope to line items proposed as the replacement for these specific expiring commitments. Useful for "show me what's being proposed to replace commitment X." Rejected with 400 on non-renewal plans (their line items have no renewal linkage; this guards against stale/wrong plan ids silently returning unrelated rows).
Default: null
order_bystring · enumOptional
Field to order results by
Default: monthly_net_savingsPossible values: monthly_net_savings``monthly_total_cost``breakeven_days``discount_rate``upfront_cost
descbooleanOptional
Sort descending (default true)
Default: true
pageinteger · min: 1OptionalDefault: 1
page_sizeinteger · min: 1 · max: 10000OptionalDefault: 20
Responses
200
OK
application/json
Headersobject
Show Header
Responseobject · CommitmentLineItem[]
Show properties
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/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
[\
{\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"is_selected": true,\
"account_id": "text",\
"contract_term": "one_year_gris",\
"contract_spec": {\
"commitment_type": "text",\
"properties": {\
"ANY_ADDITIONAL_PROPERTY": "anything"\
},\
"term": "one_year_gris",\
"payment_option": "no_upfront"\
},\
"offer": {\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"provider": "aws",\
"type": "text",\
"region": "text",\
"duration_seconds": 1,\
"instance_type": "text",\
"instance_family": "text",\
"offering_class": "standard",\
"payment_option": "no_upfront",\
"plan_type": "text",\
"product_description": "text",\
"display_name": "text",\
"guaranteed_display_name": "text",\
"is_flexible": true\
},\
"discount_rate": 1,\
"breakeven_days": null,\
"selected_amount": null,\
"recommended_amount": null,\
"commitment_upfront_cost": 1,\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
},\
"covered_services": [\
"text"\
],\
"renewal_commitment_id": "123e4567-e89b-12d3-a456-426614174000"\
}\
]
Update commitment plan line itemsDirect link to heading
post/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items/update
Atomically apply line-item edits in a single request. Two modes:
GitBook Assistant
- Explicit: pass
updates, a list where each entry carries the same fields the singular line-item update would accept (selection, account, offer-swap triple) plus theline_item_idselector.
GitBook Assistant
- Resolution: pass
target_contract_term(+ optionaltarget_payment_option/target_line_item_ids) and the server swaps every selected (or scoped) line item to the closest candidate at or below the target term. Saves the LLM having to enumerate many edits when the user wants a uniform shape change.
GitBook Assistant
Modes are mutually exclusive. All updates are applied within a single transaction — if any fails (unknown line item, invalid offer, integer-coercion error on a unit-basis offer's selected_amount), the whole call is rejected and no changes persist.
GitBook Assistant
Returns the updated plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the change. Follow up with commitment_plan_details on the returned id if you need the full breakdown. In resolution mode the response additionally carries a resolution array with one entry per scoped line item: the actual_term / actual_payment_option applied and an actual_term_reason of exact_match, fallback_closest_shorter, or no_alternative (the latter were left untouched). Surface no_alternative outcomes to the user so they understand why coverage may be partial.
GitBook Assistant
Rejected if the parent plan is currently calculating, is a system-generated default, or is locked for purchase.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Body
application/json
application/json
target_contract_termstring · enum · nullableOptional
target_payment_optionstring · enumOptional
Default: no_upfrontPossible values: no_upfront``partial_upfront``all_upfront
target_line_item_idsstring · uuid[] · nullableOptional
Default: null
updatesobject · LineItemUpdateEntry[] · min: 1 · nullableOptional
List of per-line-item updates to apply atomically. Required unless target_contract_term is set (resolution mode). Each entry's line_item_id must be on the parent plan.
Default: null
Show properties
Responses
200
OK
application/json
idstring · uuidRequired
Unique plan identifier
providerstring · enumRequired
Cloud provider (aws, azure, gcp)
Possible values: aws``azure``gcp
namestringRequired
Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')
descriptionstring · nullableOptional
Human-readable summary of the plan
is_renewalbooleanRequired
statusstring · enumRequired
Plan status (e.g. 'draft', 'in_progress', 'completed')
Possible values: new``reviewed``scheduled``completed``draft``needs_review``in_progress
is_calculatingbooleanRequired
True if the plan is still being computed
created_atstring · date-timeRequired
When the plan was generated
usage_start_datestring · date-time · nullableOptional
usage_end_datestring · date-time · nullableOptional
End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).
max_termstring · nullableRequired
Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')
minimum_commitmentnumberRequired
Minimum total spend being committed to
breakeven_daysanyRead-onlyOptional
Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand.
commitment_upfront_costnumberOptional
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
configurationobject · CommitmentPlanConfigurationOptional
Show properties
resolutionobject · HypotheticalLineItem[] · nullableOptional
Show properties
400
Bad Request
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
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
post/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items/update
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items/update HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 378
{
"target_contract_term": "one_year_gris",
"target_payment_option": "no_upfront",
"target_line_item_ids": [\
"123e4567-e89b-12d3-a456-426614174000"\
],
"updates": [\
{\
"line_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"is_selected": true,\
"account_id": "text",\
"offer_id": "123e4567-e89b-12d3-a456-426614174000",\
"lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"selected_amount": 1\
}\
]
}
200
OK
GitBook AssistantAskCopy
List the commitments being renewed by a renewal planDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/renewal-commitments
Returns the expiring commitments that a renewal plan is proposed to replace — identity, dates, guarantee info, and contract term. Ordered by end_date ascending (earliest-expiring first) so the caller surfaces the most-urgent renewals first.
GitBook Assistant
Rejected with 400 if the plan is not a renewal plan — for non-renewal plans use /line-items or /covered-resources instead.
GitBook Assistant
To filter to the commitments tied to a subset of line items, pass line_item_ids. To go the other direction (line items proposed as replacements for a given source commitment), use the renewal_commitment_ids filter on /line-items.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Query parameters
line_item_idsstring · uuid[] · nullableOptional
Optional list of line-item ids to scope to. When supplied, returns only the source commitments whose renewing line items are in this set.
Default: null
pageinteger · min: 1OptionalDefault: 1
page_sizeinteger · min: 1 · max: 200OptionalDefault: 50
Responses
200
OK
application/json
Headersobject
Show Header
Responseobject · Commitment[]
Show properties
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/beta/v1/org/{org_id}/commitment-plans/{plan_id}/renewal-commitments
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/renewal-commitments HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
[\
{\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"provider_reservation_id": "text",\
"provider": "aws",\
"display_name": "text",\
"guaranteed_display_name": "text",\
"type": "text",\
"status": "active",\
"is_active": true,\
"is_archera_guaranteed": true,\
"account_id": "text",\
"billing_account_id": "text",\
"start_date": "2026-07-27T19:35:56.493Z",\
"end_date": "2026-07-27T19:35:56.493Z",\
"duration_seconds": 1,\
"guarantee_start": "2026-07-27T19:35:56.493Z",\
"guarantee_lockin_date": "2026-07-27T19:35:56.493Z",\
"guarantee_method": null,\
"region": "text",\
"instance_type": "text",\
"instance_family": "text",\
"plan_type": "text",\
"payment_option": "no_upfront",\
"offering_class": "standard",\
"is_flexible": true,\
"instance_count": 1,\
"contract_term": "one_year_gris"\
}\
]
Compare commitment offers across a plan's line itemsDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison
Returns per-line-item offer alternatives plus plan-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line_item_ids=all selected, contract_terms=all distinct in candidates, payment_options=[no_upfront].
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Query parameters
line_item_idsstring · uuid[] · nullableOptional
Optional subset of line items to compare. If omitted, defaults to all selected line items in the plan.
Default: null
contract_termsstring · enum[] · nullableOptional
Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any line item's candidates after the payment-option filter.
Default: null
Show properties
payment_optionsstring · enum[]Optional
Payment options to include. Defaults to no_upfront only — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Pass partial_upfront / all_upfront explicitly to surface those.
Show properties
Responses
200
OK
application/json
current_totalsobject · LineItemOfferComparisonTotalsRequired
Show properties
hypothetical_totalsobject · HypotheticalTotal[]Required
One entry per (contract_term, payment_option) combination requested (or per distinct term present in candidates if contract_terms was omitted). Each entry's totals + delta_vs_current answer 'what's the plan-wide impact of this term?' in one place — no client-side summing across line items required.
Show properties
dataobject · LineItemOfferComparisonRow[]Required
Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload.
Show properties
400
Bad Request
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
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/beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
{
"current_totals": {
"commitment_financials_monthly_rate": {
"commitment_cost": {
"total": 1,
"breakdown": {
"cloud_provider_cost": {
"total": 1,
"breakdown": {
"recurring": 1,
"amortized_upfront": 1
}
},
"archera_premium": 1
}
},
"commitment_savings": {
"net": 1,
"gross": 1
},
"covered_ondemand_cost": 1
},
"commitment_upfront_cost": 1
},
"hypothetical_totals": [\
{\
"contract_term": "one_year_gris",\
"payment_option": "no_upfront",\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
},\
"commitment_upfront_cost": 1,\
"delta_vs_current": {\
"monthly_net_savings": 1,\
"monthly_commitment_cost": 1,\
"upfront_cost": 1\
},\
"line_items": [\
{\
"line_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"actual_term": "one_year_gris",\
"actual_payment_option": "no_upfront",\
"actual_term_reason": "exact_match"\
}\
]\
}\
],
"data": [\
{\
"line_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"current": {\
"is_current": true,\
"offer_id": "123e4567-e89b-12d3-a456-426614174000",\
"offer": {\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"provider": "aws",\
"type": "text",\
"region": "text",\
"duration_seconds": 1,\
"instance_type": "text",\
"instance_family": "text",\
"offering_class": "standard",\
"payment_option": "no_upfront",\
"plan_type": "text",\
"product_description": "text",\
"display_name": "text",\
"guaranteed_display_name": "text",\
"is_flexible": true\
},\
"lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"selected_amount": 1,\
"contract_term": "one_year_gris",\
"discount_rate": 1,\
"breakeven_days": 1,\
"commitment_upfront_cost": 1,\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
},\
"delta_vs_current": {\
"monthly_net_savings": 1,\
"upfront_cost": 1,\
"discount_rate": 1,\
"breakeven_days": 1\
}\
},\
"candidates": [\
{\
"is_current": true,\
"offer_id": "123e4567-e89b-12d3-a456-426614174000",\
"offer": {\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"provider": "aws",\
"type": "text",\
"region": "text",\
"duration_seconds": 1,\
"instance_type": "text",\
"instance_family": "text",\
"offering_class": "standard",\
"payment_option": "no_upfront",\
"plan_type": "text",\
"product_description": "text",\
"display_name": "text",\
"guaranteed_display_name": "text",\
"is_flexible": true\
},\
"lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"selected_amount": 1,\
"contract_term": "one_year_gris",\
"discount_rate": 1,\
"breakeven_days": 1,\
"commitment_upfront_cost": 1,\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
},\
"delta_vs_current": {\
"monthly_net_savings": 1,\
"upfront_cost": 1,\
"discount_rate": 1,\
"breakeven_days": 1\
}\
}\
]\
}\
]
}
List filterable covered-resource attributes for a planDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes
Returns the fields that can be used in the filter parameter of /commitment-plans/<plan_id>/covered-resources, scoped to the resources the plan actually covers.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Responses
200
OK
application/json
namestringRequired
fieldstringRequired
typestring · enumRequiredPossible values: boolean``integer``float``date``datetime``time``currency``percent``string``enum``uuid``tags
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
500
Internal server error
application/json
default
Default error response
application/json
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
[\
{\
"name": "text",\
"field": "text",\
"type": "boolean"\
}\
]
Get valid values for a filterable covered-resource attributeDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field}
Returns the distinct values for a given field, restricted to the resources the plan covers (and further narrowed by any search/filter passed). Use to discover valid filter values without paginating through the covered-resources list.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
fieldstring · min: 1Required
Query parameters
line_item_idsstring · uuid[] · nullableOptional
Filter to matches from specific line items
Default: null
only_selected_line_itemsbooleanOptional
Only include matches from selected line items (default true)
Default: true
searchstring · nullableOptional
Free-text ILIKE search across the resource SKU's identity and classification fields (resource id, name, account ids, service, region, instance_type, etc.). Mirrors the search lane on /resources/skus.
Default: null
filterobject · nullableOptional
JSON filter object — same {field, op, value} tree accepted by /resources/skus. Filterable on the resource SKU side: identity, tags (has with nested key/value filters), SKU classification, and the trailing-30-day spend/usage aggregates: total_cost, ondemand_cost, gross_savings (TOTAL summed over the trailing 30 days, NOT a monthly rate — same basis as /resources/skus), coverage (spend-based fraction covered by ALL existing commitments — current actuals, NOT this plan's projected coverage; that's the response's per-match projected_coverage), and uptime (fraction). All warehouse aggregates here are actuals across existing commitments, NOT plan-scoped projections. Call /covered-resources/attributes for the full filterable surface.
Default: null
Show properties
order_bystring · enumOptional
Field to order results by. Defaults to monthly_net_savings. All numeric axes are 730-hour monthly rates on the per-match plan economics, net of the Archera premium where applicable (NOT the resource's warehouse trailing-30-day actuals — those are filterable but not orderable here, on purpose, to keep sort and response framing on the same monthly basis).
Default: monthly_net_savingsPossible values: id``projected_coverage``monthly_net_savings``monthly_before_cost``monthly_after_cost``monthly_after_ondemand_cost
descbooleanOptional
Sort descending (default true)
Default: true
Responses
200
OK
application/json
object · BooleanAttributeOptional
Show properties
or
object · UUIDAttributeOptional
Show properties
or
object · StringAttributeOptional
Show properties
or
object · IntegerAttributeOptional
Show properties
or
object · FloatAttributeOptional
Show properties
or
object · CurrencyAttributeOptional
Show properties
or
object · PercentAttributeOptional
Show properties
or
object · DateTimeAttributeOptional
Show properties
or
object · DateAttributeOptional
Show properties
or
object · TimeAttributeOptional
Show properties
or
object · EnumAttributeOptional
Show properties
or
object · TagsAttributeOptional
Show properties
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/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field}
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field} HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
{
"name": "text",
"field": "text",
"type": "boolean",
"filters": [\
{\
"field": "text",\
"value": "text",\
"op": "="\
}\
]
}
Aggregated covered-resources summary for a commitment planDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary
Returns the resources a commitment plan covers, aggregated by (service, account, region, resource_type). Each row is one group: rolled-up costs, savings, spend-weighted coverage, and resource count. Sorted by net savings descending. For per-resource detail, use the paginated /covered-resources endpoint.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Query parameters
line_item_idsstring · uuid[] · nullableOptional
Filter to matches from specific line items
Default: null
only_selected_line_itemsbooleanOptional
Only include matches from selected line items (default true)
Default: true
Responses
200
OK
application/json
servicestring · nullableOptional
Cloud service name (e.g. 'AmazonEC2', 'AmazonRDS')
account_idstring · nullableOptional
Cloud account ID
regionstring · nullableOptional
Cloud region (e.g. 'us-east-1')
resource_typestring · nullableOptional
Resource type within this group — instance family for compute (e.g. 'm5'), usage type for other services (e.g. 'Fargate-GB-Hours', 'Lambda-GB-Second'), or SKU name as fallback
resource_countintegerOptional
Number of resources in this group
projected_coveragenumberOptional
Spend-based projected coverage across resources in this group (0-1), weighted by each resource's on-demand-equivalent cost. Distinct from resource.coverage (trailing-30-day actual spend-based coverage from existing commitments). For per-resource projected coverage, use the paginated /covered-resources endpoint.
commitment_financials_monthly_rateobject · CommitmentFinancialsNoRebateOptional
Show properties
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/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
[\
{\
"service": "text",\
"account_id": "text",\
"region": "text",\
"resource_type": "text",\
"resource_count": 1,\
"projected_coverage": 1,\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
}\
}\
]
Paginated covered resources for a commitment planDirect link to heading
get/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources
Returns one row per resource the plan covers, with the plan's economics scoped to that resource (coverage, monthly savings, before/after cost) and full ResourceSKU detail. Supports search, structured filter, sort, and cursor pagination — same surface idiom as /resources/skus, but scoped to the plan's matched resources. Use /covered-resources/summary for the aggregated breakdown. X-Pagination is navigation-only: it always includes page and first_page, and adds previous_page and next_page when available.
GitBook Assistant
Path parameters
org_idstring · uuidRequired
plan_idstring · uuidRequired
Query parameters
line_item_idsstring · uuid[] · nullableOptional
Filter to matches from specific line items
Default: null
only_selected_line_itemsbooleanOptional
Only include matches from selected line items (default true)
Default: true
searchstring · nullableOptional
Default: null
filterobject · nullableOptional
Default: null
Show properties
order_bystring · enumOptional
descbooleanOptional
Sort descending (default true)
Default: true
pageinteger · min: 1OptionalDefault: 1
page_sizeinteger · min: 1 · max: 100OptionalDefault: 20
Responses
200
OK
application/json
Headersobject
Show Header
Responseobject · ResourceMatchDetail[]
Show properties
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/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources
HTTP
HTTPcURLJavaScriptPython
GitBook AssistantAskCopy
GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources HTTP/1.1
Accept: */*
200
OK
GitBook AssistantAskCopy
[\
{\
"id": "123e4567-e89b-12d3-a456-426614174000",\
"line_item_id": "123e4567-e89b-12d3-a456-426614174000",\
"projected_coverage": 1,\
"commitment_financials_monthly_rate": {\
"commitment_cost": {\
"total": 1,\
"breakdown": {\
"cloud_provider_cost": {\
"total": 1,\
"breakdown": {\
"recurring": 1,\
"amortized_upfront": 1\
}\
},\
"archera_premium": 1\
}\
},\
"commitment_savings": {\
"net": 1,\
"gross": 1\
},\
"covered_ondemand_cost": 1\
},\
"resource": {\
"id": "text",\
"resource_id": "123e4567-e89b-12d3-a456-426614174000",\
"catalog_sku_id": "123e4567-e89b-12d3-a456-426614174000",\
"catalog_sku_org_id": "text",\
"provider": "aws",\
"provider_resource_id": "text",\
"provider_sku_id": "text",\
"name": "text",\
"sku_name": "text",\
"integration_id": "text",\
"billing_account_id": "text",\
"sub_account_id": "text",\
"resource_group": "text",\
"is_spot": true,\
"availability_zone": "text",\
"service": "text",\
"provider_service": "text",\
"family": "text",\
"region_code": "text",\
"full_region_name": "text",\
"instance_type": "text",\
"instance_type_family": "text",\
"usage_type": "text",\
"operation": "text",\
"operating_system": "text",\
"tenancy": "text",\
"database_engine": "text",\
"database_edition": "text",\
"cache_engine": "text",\
"is_multi_az": true,\
"is_current_generation": true,\
"license_model": "text",\
"pre_installed_sw": "text",\
"processor_architecture": "text",\
"is_reservable": true,\
"is_byol": true,\
"is_flexible": true,\
"is_serverless": true,\
"vcpu": 1,\
"memory": 1,\
"ondemand_usage_unit": "text",\
"ondemand_usage_price": 1,\
"price_currency": "text",\
"usage_start": "2026-07-27T19:35:56.493Z",\
"usage_end": "2026-07-27T19:35:56.493Z",\
"tags": {\
"ANY_ADDITIONAL_PROPERTY": "text"\
}\
}\
}\
]
PreviousAllocation Reports (Beta) NextCommitment Plan Templates (Beta)
Last updated 10 days ago
Was this helpful?
This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the privacy policy.
AcceptReject