Commitment Plans (Beta)

Agent-friendly commitment plan endpoints

List commitment plans

get

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.

Path parameters

org_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

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:

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

Responses

200

OK

application/json

idstring · uuidRequired

Unique plan identifier

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

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

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans?provider=aws HTTP/1.1
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "aws",
    "name": "text",
    "description": "text",
    "status": "new",
    "is_calculating": true,
    "created_at": "2026-05-17T10:19:31.670Z",
    "usage_start_date": "2026-05-17T10:19:31.670Z",
    "usage_end_date": "2026-05-17T10:19:31.670Z",
    "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": 7,
      "contract_specs": [
        {
          "commitment_type": "text",
          "contract_term": "one_year_gris",
          "payment_option": "no_upfront"
        }
      ],
      "resource_ids": []
    }
  }
]

Create a commitment plan

post

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.

Path parameters

org_idstring · uuidRequired

Body

application/json

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

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

Responses

200

OK

application/json

idstring · uuidRequired

Unique plan identifier

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

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

HTTPcURLJavaScriptPython

POST /beta/v1/org/{org_id}/commitment-plans HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "provider": "aws",
  "segment_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "configuration": {
    "max_upfront_cost": 0,
    "lookback_days": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  }
}

Get default commitment plans

get

Returns the three default Archera commitment plans: Recommended (30-day), Balanced (1-year), and High Savings (3-year).

Path parameters

org_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

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:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

current_coveragenumberRequired

Commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.

projected_coveragenumberRequired

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

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/default?provider=aws HTTP/1.1
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "aws",
    "name": "text",
    "description": "text",
    "status": "new",
    "is_calculating": true,
    "created_at": "2026-05-17T10:19:31.670Z",
    "usage_start_date": "2026-05-17T10:19:31.670Z",
    "usage_end_date": "2026-05-17T10:19:31.670Z",
    "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": 7,
      "contract_specs": [
        {
          "commitment_type": "text",
          "contract_term": "one_year_gris",
          "payment_option": "no_upfront"
        }
      ],
      "resource_ids": []
    },
    "current_coverage": 1,
    "projected_coverage": 1
  }
]

Get recommended commitment plan

get

Returns the single recommended commitment plan for the organization. This is typically the 30-day Recommended plan. Returns 204 if no plan is available.

Path parameters

org_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

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:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

current_coveragenumberRequired

Commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.

projected_coveragenumberRequired

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

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/recommended?provider=aws HTTP/1.1
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  },
  "current_coverage": 1,
  "projected_coverage": 1
}

Get commitment plan details

get

Returns details for a specific commitment plan by ID, including per-service breakdowns.

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:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

current_coveragenumberRequired

Commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.

projected_coveragenumberRequired

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

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}

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  },
  "current_coverage": 1,
  "projected_coverage": 1,
  "covered_services": [
    {
      "service_name": "text",
      "num_commitments": 1,
      "current_coverage": 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
      }
    }
  ]
}

Update a commitment plan

put

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.

Path parameters

org_idstring · uuidRequired

plan_idstring · uuidRequired

Body

application/json

namestringOptional

New plan name

Responses

200

OK

application/json

idstring · uuidRequired

Unique plan identifier

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

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}

HTTPcURLJavaScriptPython

PUT /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 198

{
  "name": "text",
  "configuration": {
    "max_upfront_cost": 0,
    "lookback_days": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  }
}

Delete a commitment plan

delete

Delete a commitment plan. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. Irreversible.

Path parameters

org_idstring · uuidRequired

plan_idstring · uuidRequired

Responses

204

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}

HTTPcURLJavaScriptPython

DELETE /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1
Accept: */*

No content

Apply (purchase) a commitment plan

post

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.

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:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

current_coveragenumberRequired

Commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan.

projected_coveragenumberRequired

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

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

HTTPcURLJavaScriptPython

POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply HTTP/1.1
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  },
  "current_coverage": 1,
  "projected_coverage": 1,
  "covered_services": [
    {
      "service_name": "text",
      "num_commitments": 1,
      "current_coverage": 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
      }
    }
  ]
}

Copy a commitment plan, optionally applying line-item edits

post

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).

Optionally apply line-item edits during the copy via two mutually exclusive modes:

• Explicit: pass line_item_updates referencing the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically.

• Resolution: pass target_contract_term (+ optional target_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.

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.

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.

Rejected if the source plan is currently being calculated.

Path parameters

org_idstring · uuidRequired

plan_idstring · uuidRequired

Body

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:

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:

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

Responses

200

OK

application/json

idstring · uuidRequired

Unique plan identifier

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

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

HTTPcURLJavaScriptPython

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  },
  "resolution": [
    {
      "line_item_id": "123e4567-e89b-12d3-a456-426614174000",
      "actual_term": "one_year_gris",
      "actual_payment_option": "no_upfront",
      "actual_term_reason": "exact_match"
    }
  ]
}

Get commitment plan line items

get

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).

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

order_bystring · enumOptional

Field to order results by

Default: monthly_net_savingsPossible values:

descbooleanOptional

Sort descending (default true)

Default: true

pageinteger · min: 1OptionalDefault: 1

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

Responses

200

OK

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

/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items HTTP/1.1
Accept: */*

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

Update commitment plan line items

post

Atomically apply line-item edits in a single request. Two modes:

• 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 the line_item_id selector.

• Resolution: pass target_contract_term (+ optional target_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.

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.

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.

Rejected if the parent plan is currently calculating, is a system-generated default, or is locked for purchase.

Path parameters

org_idstring · uuidRequired

plan_idstring · uuidRequired

Body

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:

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:

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

Responses

200

OK

application/json

idstring · uuidRequired

Unique plan identifier

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:

namestringRequired

Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')

descriptionstring · nullableOptional

Human-readable summary of the plan

statusstring · enumRequired

Plan status (e.g. 'draft', 'in_progress', 'completed')

Possible values:

is_calculatingbooleanRequired

True if the plan is still being computed

created_atstring · date-timeRequired

When the plan was generated

usage_start_datestring · date-timeOptional

Start of the usage window the plan was computed from.

usage_end_datestring · date-timeOptional

End of the usage window the plan was computed from.

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.

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

HTTPcURLJavaScriptPython

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "aws",
  "name": "text",
  "description": "text",
  "status": "new",
  "is_calculating": true,
  "created_at": "2026-05-17T10:19:31.670Z",
  "usage_start_date": "2026-05-17T10:19:31.670Z",
  "usage_end_date": "2026-05-17T10:19:31.670Z",
  "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": 7,
    "contract_specs": [
      {
        "commitment_type": "text",
        "contract_term": "one_year_gris",
        "payment_option": "no_upfront"
      }
    ],
    "resource_ids": []
  },
  "resolution": [
    {
      "line_item_id": "123e4567-e89b-12d3-a456-426614174000",
      "actual_term": "one_year_gris",
      "actual_payment_option": "no_upfront",
      "actual_term_reason": "exact_match"
    }
  ]
}

Compare commitment offers across a plan's line items

get

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].

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

Responses

200

OK

application/json

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

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison HTTP/1.1
Accept: */*

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

get

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.

Path parameters

org_idstring · uuidRequired

plan_idstring · uuidRequired

Responses

200

OK

application/json

namestringRequired

fieldstringRequired

typestring · enumRequiredPossible values:

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

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes HTTP/1.1
Accept: */*

[
  {
    "name": "text",
    "field": "text",
    "type": "boolean"
  }
]

Get valid values for a filterable covered-resource attribute

get

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.

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

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:

descbooleanOptional

Sort descending (default true)

Default: true

Responses

200

OK

application/json

or

or

or

or

or

or

or

or

or

or

or

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}

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field} HTTP/1.1
Accept: */*

{
  "name": "text",
  "field": "text",
  "type": "boolean",
  "filters": [
    {
      "field": "text",
      "value": "text",
      "op": "="
    }
  ]
}

Aggregated covered-resources summary for a commitment plan

get

Returns the resources a commitment plan covers, aggregated by (service, account, region, resource_type). Each row is one group: rolled-up costs, savings, mean coverage, and resource count. Sorted by net savings descending. For per-resource detail, use the paginated /covered-resources endpoint.

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

Mean projected coverage across resources in this group (0-1) — the fraction of each resource's usage THIS plan would cover, averaged. Post-plan / projected: distinct from resource.coverage (the trailing-30-day actual coverage from existing commitments). For per-resource projected coverage, use the paginated /covered-resources endpoint.

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

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary HTTP/1.1
Accept: */*

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

get

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.

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

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

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:

descbooleanOptional

Sort descending (default true)

Default: true

pageinteger · min: 1OptionalDefault: 1

page_sizeinteger · min: 1 · max: 100OptionalDefault: 20

Responses

200

OK

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

/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources HTTP/1.1
Accept: */*

[
  {
    "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-05-17T10:19:31.670Z",
      "usage_end": "2026-05-17T10:19:31.670Z",
      "tags": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  }
]