Tools

The server registers 60 tools, 21 of which write. This page is generated from mcp-manifest.json, the surface the running server advertises, so the names, parameters, enums and defaults below are the ones it registers. The text under each heading is what a model reads verbatim when it picks between them.

Conventions

Of the 60, 39 are annotated readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false: they read, and the same arguments return the same answer. The other 21 write, marked below, and carry readOnlyHint false so your client asks you before calling one. None of them touches a cloud resource itself: they record a decision, settle how a change is delivered, or put it in the rollout queue, and LevelFour's own executor applies it afterwards.

No tool takes a tenant, an organization or an account argument. The organization comes from the credential, because it is a separate Postgres database rather than a filter on a shared one. See Connecting a client.

provider is a plain string, not an enum. Which providers exist is a fact about your organization, so the server validates the value at call time and names the valid ones in the error. Read levelfour://providers or call get-identity first.

A default of none means the parameter is optional and omitted, and the description says what the server does without it. Dates are YYYY-MM-DD. Every page_size and limit caps at 50, and a list tool returns has_next_page and next_page already computed.

Results come back as text rather than a structured content block. Reading a result has the shapes, the pagination envelope every list shares, and what truncation and errors look like.

connect-version-control

Purpose: Start connecting the organization's GitHub, which the IaC format needs.

Returns: the GitHub App install link. An organization owner opens it, chooses which repositories LevelFour may see, and GitHub then returns them to a LevelFour page that finishes the connection. Both halves are theirs to do: LevelFour cannot approve an app on their behalf.

When to use: When get-savings-readiness reports no version control connection.

NOT for: Choosing a repository for one savings, which is set-implementation-method once this is done. Not for GitLab either: a GitLab connection cannot carry the IaC format, because binding a repository to a recommendation keys on a GitHub installation.

Parameters

Takes no arguments.

create-commitment-purchase

Purpose: Raise a new Savings Plan from its proposal, or a Reserved Instance or Savings Plan on terms of the user's own, as a savings nobody has decided yet. It raises and buys nothing.

Returns: the savings it was raised as (its id starts BUY-), the payer and plan type, the 12-month No Upfront commitment in dollars an hour, the profile it came from (null for a size of the user's own) and the guards that capped it, the monthly savings it is booked at, grain "daily" and source "cur", whether this call created it, and next, the tools that carry it from here. With neither profile nor commitment_hourly it raises balanced. Calling again with the same pick returns the purchase already raised; another pick is refused while it stands undecided, and with new_purchase that refusal names it. An identical purchase already awaiting approval, accepted, released or sent in the last 24 hours is refused and named too, so ask the user before raising a second one with confirm_additional. With new_purchase it raises exactly that offering after checking AWS still sells it: kind, origin (recommended when it matches LevelFour's size, else custom), target, resource and quantity or the commitment, term, payment, the approval an admin accepts (term_total, upfront, currency), its quote, and a Manual Setup guide. The buying account must be one of the organization's AWS accounts.

When to use: The user read get-commitment-purchase-plan, list-commitment-offerings or preview-commitment-purchase and chose what to buy.

NOT for: Changing the size of a purchase already raised, which update-commitment-purchase does. Replaying a size first, which preview-commitment-purchase does. Renewing a commitment that is expiring, which create-commitment-renewal does.

Parameters

create-commitment-renewal

Purpose: Raise the renewal of an expiring Reserved Instance or Savings Plan as a savings.

Returns: the savings the renewal was raised as (its id starts RENEW-), the offering and quantity it buys, whether this call created it, whether nobody has decided it yet (rebindable), the accepted changes that should land before it, and next, the tools that carry it from here. A Savings Plan renewal also carries sized_on: its quantity was sized on the billing export's daily totals, which can read higher than the quietest hour. Calling again returns the renewal already raised rather than a second one, and a renewal rejected before anybody released it is raised again as a new one.

When to use: The user has read the renewal plan or its options and chosen what to renew.

NOT for: Pricing the terms, which is get-commitment-renewal-options. Not for pointing an undecided renewal at another option either: that is refused here, and the user changes it in the Dashboard or rejects it with decide-recommendation and raises again. Nothing is bought here: the purchase waits for an organization admin's release.

Parameters

create-cost-alert

Purpose: Arm a cost alert.

Returns: the stored rule.

When to use: After get-cost-alert-suggestions, and only with a threshold the customer named or the suggestions justified. A commitment rule watches an expiry, a lapse, falling utilization, saturation or a contract overage on its own clock rather than the month's.

NOT for: Changing an existing rule, which update-cost-alert does. Read list-cost-alerts first, because a second rule on the same slice notifies twice.

Parameters

create-savings-grant

Purpose: Mint the scoped access grant that Automated Savings runs through, on AWS, or on Google Cloud for an organization that has Google Cloud Automated Savings turned on.

Returns: the new grant and the page where the customer authorizes it. Creating it changes nothing in their account: it writes a scoped policy and waits. On AWS the access exists only once they launch the CloudFormation stack themselves. On Google Cloud the result also carries connect_command, which they paste into their own Cloud Shell to bind the time-boxed roles. Neither is something LevelFour can do on their behalf.

When to use: When the user wants an Automated savings to be able to run and no grant exists yet. This mints it and returns where they authorize it.

NOT for: Checking on one, use get-savings-grant. Asking what a savings still needs, use get-savings-readiness. Making the change, which runs after the grant connects. Not for minting a second grant either: a live one already covers the recommendation, and two launched stacks add permissions to the role rather than replacing them, so that is refused here.

Parameters

create-virtual-tag

Purpose: Define a new virtual tag from a full definition.

Returns: the tag as get-tag reads it, with the reprocessing job. Spend is reprocessed from effective_from, so the figures fill in as the job runs.

When to use: Only when the user asked, in this conversation, for a tag to be created. Try the rules with preview-virtual-tag first.

NOT for: Changing a tag that exists, use update-virtual-tag. Provider tags, which are read from the bill and never modified. This changes how LevelFour allocates spend in its own reports, and nothing in a cloud account.

Parameters

create-virtual-tag-config

Purpose: Add one config to a virtual tag, leaving the rest of it alone.

Returns: the tag as get-tag reads it, with the reprocessing job.

When to use: Adding a value to a tag that exists, which is the common change. Prefer this over sending a whole definition back, because that clears anything you leave out.

Examples: give the data team the Redshift spend: filter with one rule for aws whose condition is service is Amazon Redshift, assign type value with value data.

NOT for: A tag that does not exist yet, use create-virtual-tag. The config lands last, which is lowest precedence, so if an earlier config already claims those lines it assigns nothing until you move it with update-virtual-tag-config-order.

Parameters

decide-recommendation

Purpose: Record the user's decision to accept or reject one savings recommendation.

Returns: the recommendation's new status and the decision as it was recorded.

When to use: When the user has named a recommendation and said to accept or reject it. This books that decision, so it is the tool for "accept REC-1234" or "reject REC-5678".

NOT for: Making the change. Accepting books a decision and stamps the approver; it does not resize, delete or modify anything. To settle how it gets delivered use set-implementation-method, and to put it in the rollout queue start-rollout. Not for reversing a decision, which only the dashboard can do. Not for a recommendation waiting on approval for a rollout a teammate requested either: answering them is release-rollout, and accepting here is refused. If the user has not seen the figures they are deciding on, get-recommendation puts the monthly saving and the operational impact in front of them first.

Parameters

delete-cost-alert

Purpose: Delete a cost alert, and every firing it has recorded with it.

Returns: the id and name of the rule that is gone.

When to use: Only when the user asked, in this conversation, for this rule to be deleted. Read it with list-cost-alerts first and name it back, because nothing brings it or its history back afterwards.

NOT for: A rule firing on spend somebody accepted, which pause-cost-alert silences and keeps, history included.

Parameters

delete-virtual-tag

Purpose: Delete a virtual tag and the spend allocation derived from it.

Returns: outcome deleted, with the name and id of the tag that went.

When to use: Only when the user asked, in this conversation, for the tag to be deleted. Read it with get-tag first, both for its expected_version and to report what is about to go.

NOT for: Provider tags, which are read from the bill. A tag another virtual tag reads is refused rather than cascaded: change the tag that reads it first.

Parameters

delete-virtual-tag-config

Purpose: Remove one config from a virtual tag, leaving the rest of it alone.

Returns: the tag as get-tag reads it, with the reprocessing job. A value no remaining config assigns disappears with it, and the spend it held becomes unallocated.

When to use: A team that no longer needs its own line. Read the tag with get-tag first and report which value goes, because the number alone does not say.

NOT for: Removing the whole tag, use delete-virtual-tag.

Parameters

get-commitment

Purpose: One Reserved Instance or Savings Plan in full.

Returns: its term, payment option, holder account and the accounts consuming it, its utilization history, the events on it, and any savings attached to it. A reservation carries its coverage; a Savings Plan does not, because coverage is not reported by plan type. figures_source "cur" means utilization, protects and rightsizing were read off the commitment's own lines on the bill; "cost_explorer" means they are the service's figure shared by fee, an estimate to quote as one.

When to use: After list-commitments names one worth opening.

NOT for: Comparing several, use list-commitments. Planning a replacement, use get-commitment-renewal-plan.

Parameters

get-commitment-coverage

Purpose: How much of the eligible bill is protected by a commitment, and how much is not.

Returns: coverage per service and the covered spend per consuming account, with the on-demand remainder beside it so the percentage names its own denominator, weighted by dollars. With months, AWS only, series holds the organization, organizations each payer and account_series each account where workloads run, month by month. Coverage there compares instance hours at public on-demand prices, covered_on_demand against uncovered_on_demand. The commitment dollars sit apart: covered_cost is what the account's usage consumed, shared_in_cost the part held by another account, shared_out_cost its own commitments used elsewhere, and held_unused_cost what they left idle after the organization shared them. A commitment idle in its holder's usage is not waste when shared_out_cost shows another account used it; only held_unused_cost is. utilization_pct is of the commitments that covered the account. held_unused_cost and utilization_pct are null while complete is false. A payer holding idle commitment with a cross_account_share_pct under 5 may have sharing limited. For GCP, coverage and utilization are month to date per project and service, in projects. A spend-based commitment's fee may sit on its billing account, where its utilization is measured.

When to use: "How exposed are we to on-demand rates", or before sizing a purchase.

NOT for: Whether a commitment you already hold is being used, which divides by what was purchased rather than by the bill: use get-commitment-utilization.

Parameters

get-commitment-overview

Purpose: The Reserved Instance and Savings Plan position, in aggregate.

Returns: the per-service split of utilization and coverage, what is committed, and how many commitments are live and how many expire soon.

When to use: "How are we doing on commitments", as the first read before a narrower one.

NOT for: A single figure for coverage or utilization, which are separate questions: get-commitment-coverage and get-commitment-utilization. The effective savings rate, use get-commitment-savings-rate. On-demand spend, use get-cost-breakdown.

Parameters

get-commitment-purchase-plan

Purpose: What to commit to that is not committed to yet.

Returns: the on-demand base a Savings Plan could cover and no commitment does, per payer, plan type, service and platform, over the last 30 complete days of the daily bill, alongside the purchases that would cover it. Each row carries its average, its quietest day and suggested_commitment_hourly, that floor in plan commitment dollars an hour, and names its grain and source. A day averages its hours, so a daily floor sits at or above the hourly one: say so when sizing from it. A payer without detailed billing gets Cost Explorer's hourly figures with suggested_commitment_hourly 0, which is visibility, not a size. proposals holds one 12-month No Upfront Savings Plan per payer and plan type, sized on the daily floor over 60 days after what is already bought or agreed (ledger) and capped by AWS's own recommendation (aws): three profiles, conservative, balanced, the one recommended, and max_savings, each in commitment dollars an hour with the utilization, coverage and monthly savings it would have had. unavailable_reason says why a proposal carries no size, and raised names the purchase already raised from it that nobody has decided yet, or is null. reservations holds the new Reserved Instances LevelFour would buy for usage no Savings Plan covers (licence-included engines, Redshift, MemoryDB and older classes), each with its target, class, quantity, term, the offering it would buy, its quote over the measured usage, a note (licensed_engine or size_flexible), unavailable_reason, quota_blocked when the RDS quota cannot hold it, and raised. schedule holds the tranches of any purchase schedule, each with its size, day, status and the reason it last shrank or was skipped. automation, present only when the organization has commitments automation, holds the limits LevelFour buys within: mode (approval asks an admin before each purchase), paused, the monthly and per-purchase caps and what was bought this UTC month in commitment dollars an hour, the account that buys for each payer, and blockers. LevelFour buys on its own only in autonomous mode, and only a tranche whose access grant an admin connected. To replay any other commitment, use preview-commitment-purchase. AWS only.

When to use: "What should we buy", or turning an uncovered base into a shortlist.

NOT for: Replacing something that is expiring, use get-commitment-renewal-plan. Buying: create-commitment-purchase raises the proposal or reservation the user chooses as a savings, and buys nothing.

Parameters

Takes no arguments.

get-commitment-renewal-options

Purpose: Every term an expiring commitment could be replaced with, priced and sized.

Returns: the contract priced again as it stands, beside each other term its shape is sold on today, with the quantity this customer's own usage supports, what each costs over the term and per year, and how much of each would sit idle or spill to on demand. sizing_basis says where the quantity came from: "utilization" and "plan_utilization" from the commitment's own fee line, which can only argue for buying less; "family" adds the on-demand usage of its family and engine held on nine days in ten, the only basis that recommends more than is held; "unmeasured" where no series could defend a number, so the quantity held stands. "measured" appears only on options an earlier sweep priced. decision "let_expire" means the commitment was used too little to pay for itself: every term is priced at the quantity held for comparison and none is recommended. A size-flexible RDS, ElastiCache or MemoryDB reservation can be renewed as a larger class of its family: classes lists every class it was priced in and what one reservation of each covers, and the options are the class recommended unless resource names another. On an option, resource is the class bought, quantity is counted in that class, held_units_equivalent is the same quantity in the class held, and quota_blocked means the account could not hold that many reservations in any class. The contract is always the class held.

When to use: "Should we renew this as it stands", comparing a one year against a three year term or a payment option against the one running, or pricing the renewal as another class.

NOT for: Buying. Nothing here places an order: create-commitment-renewal raises the option the user picks, by its offering_id and quantity.

Parameters

get-commitment-renewal-plan

Purpose: What to repurchase when a commitment expires, and the instant to buy after.

Returns: units held against the average the sized series measured, the quantity the renewal options recommend (0 with decision "let_expire" when it was used too little to pay for itself), the basis it was sized on, what the renewal protects kept separate from what right-sizing would save, and the pending changes that should land before the renewal so their capacity is not reserved. Units are in the class held; resource_recommended and quantity_recommended name the class the recommended option buys and how many, which differ where a size-flexible RDS renewal buys a larger class. superseded_by names the commitment that already renewed this one, started at superseded_at, and no_recent_usage means nothing of its family and engine ran last week; either way no renewal is raised.

When to use: "What expires this month and what should I buy", or sizing a renewal.

NOT for: Buying anything. create-commitment-renewal raises the renewal the user chooses, and nothing is bought until an organization admin releases it. Each pending change names a recommendation id: open it with get-recommendation and book it with decide-recommendation.

Parameters

get-commitment-savings-rate

Purpose: The effective savings rate (ESR): what the organization actually pays against public on-demand rates, after the commitment it paid for and left idle.

Returns: the rate for the organization and for each account, splitting what a negotiated agreement earns from what commitments earn, plus how much of the scope could be measured. An account that bought nothing still shows a healthy blended rate, which is why the split matters. esr_pct is the rate after waste: total savings minus unused_commitment_cost, over the on-demand equivalent, with idle commitment charged to the account that bought it. It is null for a month still being billed; for the headline figure, call again with period set to latest_complete_period. With months, series holds the organization, organizations each payer and account_series each account, month by month, and complete false marks a month still being billed. AWS only; the on-demand baseline exists for no other provider.

When to use: "What is our effective savings rate", or finding the accounts leaving money on the table.

NOT for: Money already booked against a recommendation, use get-savings-realized.

Parameters

get-commitment-utilization

Purpose: How much of what was bought is actually being used.

Returns: one entry per service for reservations, or per plan type for plans, each measured on its own, with the hours or units behind the percentage and a series over the window.

When to use: "Are we paying for capacity nobody uses", or sizing down before a renewal.

NOT for: How much of the bill a commitment protects, which is a different denominator and lives in get-commitment-coverage. Full utilization at low coverage is saturation, and the action it calls for is buying more.

Parameters

get-cost-alert-suggestions

Purpose: Alert rules this account's own billing history would support.

Returns: proposed rules in the same grammar a person would type, plus the baseline behind them and how much history stands behind it.

When to use: Asked to set up alerting, or asked what a threshold should be. Propose from here rather than choosing a number: every figure is a statistic over this customer's own bill, so it can be defended.

NOT for: An account connected too recently to calibrate, where maturity reads 'none' and no rule is proposed at all.

Parameters

get-cost-breakdown

Purpose: Break spend down into its largest components over a period.

Returns: a paginated, sorted list of cost lines with amounts and shares. With group_by, returns totals per value of that dimension instead of the list, with no pages to walk.

When to use: After get-cost-summary, to answer "what is driving it". Ask one broad question first rather than one call per service. The window is one calendar month unless start_date and end_date are both given. For "what does each region cost", "compare our accounts" or any per-region, per-account or per-service total, pass group_by rather than paging the lines and adding them up: a line is one service in one region in one account, so a month is thousands of them and a tally over pages is both slow and wrong.

Examples: top services this month: no arguments. Largest accounts in July: period="2026-07", sort_by="account_id". What each region costs: group_by="region". Compare accounts: group_by="account_id". Spend per team: group_by="virtual_tag", virtual_tag_key="Teams". One team's spend by service: group_by="service", virtual_tag_key="Teams", virtual_tag_value=["data"].

NOT for: Explaining a change over time, use get-cost-growth. Dating when a jump started, use get-cost-series. Savings opportunities, use list-recommendations. How a virtual tag assigns its values, use get-tag.

Parameters

get-cost-forecast

Purpose: Projected spend for the end of the current month.

Returns: the forecast figure, its confidence range, and the basis it was derived from: how much is already booked, the daily run rate, how many days are left to project, the day the actuals stop (actuals_through), how many of the trailing 30 days the run rate was drawn from (daily_rate_sample_days) and how many of those days carried almost nothing (daily_rate_thin_days).

When to use: "Where will we land this month." Read the basis before quoting the figure. A run rate drawn from a handful of days, actuals that stopped several days ago, or thin days in the window all mean the projection rests on less than it looks, and that belongs in the answer. Thin days usually mean an account stopped delivering billing data rather than that spend fell, so list-accounts is the next call rather than a conclusion.

NOT for: Historical spend, use get-cost-summary. A horizon beyond this month, which LevelFour does not forecast. LevelFour has no budget object either, so if the user asks whether they will exceed a budget you must ask them for the number.

Parameters

get-cost-growth

Purpose: Which services grew the most, and by how much.

Returns: services ranked by how many dollars they added, with the percentage beside each, plus the two windows compared and how many days each covers, so a partial month is visible rather than silent.

When to use: "Why did the bill go up." Keep the default compare_to unless the user asked specifically about calendar months.

NOT for: Absolute spend ranking, use get-cost-breakdown. Unexpected spikes specifically, use list-anomalies.

Parameters

get-cost-series

Purpose: Daily spend over a date range, as a time series.

Returns: one point per day with the total for that day, and providers_covered naming the clouds those totals span. This is the only cost tool that covers every connected cloud at once, so a figure from here is not comparable with one from a single-provider tool unless providers_covered says it is.

When to use: To date a step change. When the bill jumped and you need to know which day it started, this is the only tool that can tell you. Pair it with get-cost-breakdown over the same window to attribute the jump. A day missing from the series had no rows at all, which is different from a day that cost nothing.

NOT for: Month totals, use get-cost-summary. Splitting a day by service, use get-cost-breakdown for that window.

Parameters

get-cost-summary

Purpose: Current cloud spend and where it is heading, or one month's total.

Returns: with a period, that month's spend and its change on the previous month, and nothing else. Without one: total spend, per-provider totals, month-over-month change and the monthly series.

When to use: The opening question, "what are we spending". For "what did we spend in July", pass period="2026-07" rather than reading it out of the series.

NOT for: Spend split by service, account or tag, use get-cost-breakdown. A day-level series, use get-cost-series.

Parameters

get-costs-by-tag

Purpose: Spend grouped by the value of a tag, for showback and chargeback.

Returns: spend per tag value, plus allocation coverage showing how much spend carries the tag. Called with no tag_key, returns the keys available, each with its origin: provider for a cost allocation tag read from the bill, virtual for a tag LevelFour assigns from rules. A virtual key also returns unallocated, the spend no rule assigned.

When to use: "What does team X cost", or any per-team, per-environment or per-owner question. Read the coverage figure, or unallocated, before reporting a total: untagged spend is not zero spend.

Examples: discover keys: no arguments. Then: tag_key="team".

NOT for: Per-service or per-account splits, use get-cost-breakdown, which takes the same virtual_tag_key beside a group_by. How a virtual tag assigns its values, use get-tag.

Parameters

get-execution-logs

Purpose: What one step of a rollout ran, and what it printed.

Returns: the commands and output recorded for a single step. These are LevelFour's own execution records, written by whatever applied the change; report them as such rather than as something you ran.

When to use: When the user asks what a rollout step actually ran or printed.

NOT for: The shape of the rollout, use get-implementation-status, which lists the steps and their states far more cheaply. Reading every step at once: output here is unbounded operator text, so this serves one step and names the others.

Parameters

get-identity

Purpose: Identify the connected LevelFour organization and what it has access to.

Returns: organization plan, the cloud providers that have data, and remaining evaluation runs.

When to use: To check the connection works, or when a provider argument was rejected and you need the valid values. You do not need to call this before every analysis.

NOT for: Cloud account ids or names, use list-accounts. Spend figures, use get-cost-summary.

Parameters

Takes no arguments.

get-implementation-status

Purpose: Where one savings has got to: decided, waiting on an approver, or rolling out.

Returns: the decision, the chosen delivery format, whether that format can actually run and what is blocking it if not, who asked for a rollout still waiting on approval, and the steps of a rollout under way with the state of each.

When to use: "Did that go through", "what is it waiting on", "why has nothing happened". Also before start-rollout, because it names the blocker in the same words that tool refuses with.

NOT for: What a savings needs before it can start, use get-savings-readiness. The commands a step ran, use get-execution-logs. The case for the savings, use get-recommendation. Watching in a loop: a rollout can take 12 to 72 hours to begin, so an empty pipeline means it has not started, not that it is stuck, and the answer to "is it done yet" is another call later rather than another call now.

Parameters

get-manual-instructions

Purpose: The step-by-step guide for applying one savings by hand.

Returns: the customer-facing instructions as markdown, written for the person doing the work in their own cloud console, plus the resources the change touches.

When to use: When the delivery format is manual and the user is ready to make the change, or is deciding whether they can. This is the whole of the manual path: nothing is queued and no rollout runs, because the customer applies it themselves.

NOT for: The other formats. Automated Savings and IaC are applied by LevelFour and have their own prerequisites, which get-savings-readiness names. Not for whether the work is done either: that is settled separately and get-implementation-status reports it.

Parameters

get-recommendation

Purpose: The full case for one savings recommendation.

Returns: financials, the resources in scope, what will change, risk assessment, metrics, the delivery formats this savings backs in available_methods and the one chosen in implementation_method, where the decision stands, and dashboard_url, the saving's page in LevelFour, which is the link to give anyone asking for this saving's link. resource_console_url opens the resource in the cloud console instead. display_status is the word every LevelFour surface prints; status here is the stored column and can read differently. An id that names no saving returns status not_found with the id as typed in requested_id and up to three candidates, the closest ids, so answer from those rather than guessing another.

When to use: After list-recommendations, when the user asks about a specific id, and before recording any decision on it.

NOT for: Making the change. To record the user's accept or reject, use decide-recommendation; to settle the delivery format, set-implementation-method; to start the rollout, start-rollout. Not for a rollout already under way either, use get-implementation-status. Not for the hands-on guide: manual_instructions is withheld here and get-manual-instructions serves it. Not for scanning the backlog, use the list tool.

Parameters

get-savings-grant

Purpose: The state of the Automated Savings access grant on one recommendation.

Returns: the grant's status, when it expires, what it is scoped to, and where the customer authorizes it. A grant reaches 'connected' only when they launch it in their own AWS console, which LevelFour cannot do for them and cannot hurry.

When to use: After create-savings-grant, to see whether the customer has authorized it yet, or when get-savings-readiness reports a grant blocker and you want the detail.

NOT for: Creating one, use create-savings-grant. Whether the savings itself can run, use get-savings-readiness, which weighs this alongside everything else. Do not poll this in a tight loop: authorizing is a person opening a console, so ask again later rather than again now.

Parameters

get-savings-overview

Purpose: How the savings backlog splits across its statuses, in count and in money.

Returns: a count and a monthly savings figure per status (available, pending, awaiting_approval, processing, optimized, rejected, unavailable) plus the total number of recommendations, for one provider.

When to use: "How many savings are waiting on us", "how much is still open", or to size a status before listing it. Cheaper than paging list-recommendations to count rows.

NOT for: The individual opportunities, use list-recommendations. The organization-wide unbooked total, use get-savings-potential. Savings already booked, use get-savings-realized. These are separate quantities and summing across them is wrong: the optimized bucket is work already applied and the unavailable bucket is locked by the plan.

Parameters

get-savings-potential

Purpose: Total unbooked opportunity across all recommendations, with per-status counts.

Returns: open potential savings split by provider, and a per-status breakdown of the whole catalog. The per-status figures are separate quantities and must not be summed: optimized is work already applied, unavailable is locked by the plan.

When to use: "How much could we save in total", or to size the backlog before listing it.

NOT for: Savings already achieved, use get-savings-realized. Individual opportunities, use list-recommendations.

Parameters

Takes no arguments.

get-savings-readiness

Purpose: What still has to happen before a savings can be delivered each way.

Returns: one entry per format this savings backs, each saying whether it can run now and, when it cannot, the single thing that would clear it and the tool that does so. A ready IaC format also names the repositories its pull request would open against, which is usually a binding made long before this conversation. Pass a method to ask about one.

When to use: Before start-rollout, or whenever the user asks why a savings has not moved. It answers "what do I need" in one call rather than a refusal at a time.

NOT for: Where a rollout that already started has got to, use get-implementation-status. The case for the savings, use get-recommendation. Polling this while a customer authorizes a grant is fine, but a grant can take a while to connect, so leave time between calls.

Parameters

get-savings-realized

Purpose: Savings already realized and booked, with who approved them.

Returns: realized totals, ROI and payback, plus a line-item history.

When to use: "How much have we actually saved", or any question about past results. Each ledger row carries a full monthly rate, so a sum across rows is a run rate, not a period total.

NOT for: Opportunities not yet applied, use get-savings-potential. Realized and potential savings must never be added together.

Parameters

get-tag

Purpose: One tag key in full: how a virtual tag assigns its values, and where its spend lands.

Returns: spend and resource count per value and unallocated_spend. For a virtual tag, also its collapsed keys and configs as sentences in precedence order, definition with the same rules in the shape update-virtual-tag takes, rules_version, and the latest reprocessing job. Figures are not final while that job runs.

When to use: "How is our Teams tag defined", "why is this cost unallocated", or before changing a virtual tag: edit its definition and send it back with expected_version set to its rules_version.

NOT for: Spend split by service within each value, use get-costs-by-tag. Trying rules out before saving them, use preview-virtual-tag.

Parameters

get-usage-costs

Purpose: Billable quantity and cost per unit, grouped by usage type, and what a usage type is.

Returns: a paginated list of spend, quantity, unit and derived unit cost per usage type, largest first. A row whose quantity is not a countable unit carries no derived rate. Name a usage_type and each row also carries the services charging it, the regions and accounts it appears in and the days it was billed on.

When to use: To ground a savings claim in measured consumption, to tell a price change apart from a volume change, or to say what a code on the bill means. USE1-CachedData:Redis is answered by reading it here, because the row names the service and the region.

NOT for: Spend totals, use get-cost-breakdown. Note that usage quantity, not cost, is the reliable idleness signal here, because the cost columns round to cents.

Parameters

list-accounts

Purpose: The cloud accounts connected to this organization.

Returns: account id, name, provider, region, connection status, and whether detailed billing data is flowing for each.

When to use: To turn an account id seen in a cost or recommendation row into a name, to answer "which accounts are connected", or to check why an account has no data.

NOT for: Spend per account, use get-cost-breakdown with sort_by="account_id".

Parameters

list-anomalies

Purpose: Detected cost anomalies, meaning unexpected spikes.

Returns: anomalies with service, magnitude, detection time and status, plus counts by severity.

When to use: "Did anything spike", or investigating an unexpected increase in a past month. With no start and end this spans every anomaly ever detected, so pass both to ask about one month. The window is matched against the day a spike began, not the day it was detected.

NOT for: Expected or gradual growth, use get-cost-growth.

Parameters

list-approval-requests

Purpose: Rollouts waiting on an admin to release them, oldest first.

Returns: the recommendation, its monthly saving, who asked, when they asked, and the delivery format they proposed, which can be absent.

When to use: "What is waiting on me", "what needs approving". Then release-rollout to release one.

NOT for: The savings backlog, use list-recommendations. Deciding whether a savings is worth doing, open it with get-recommendation first: this answers who is waiting, not whether to say yes.

Parameters

Takes no arguments.

list-commitment-contracts

Purpose: Contracted spend floors that behave like a commitment but appear in no provider commitment view.

Returns: each vendor's contracted monthly floor beside the metered usage billing on top of it, with the months behind both, and whether the overage has passed the floor it sits under.

When to use: "What else are we committed to", or when a marketplace bill grows faster than the contract that was meant to cap it.

NOT for: Reserved Instances and Savings Plans, use list-commitments.

Parameters

Takes no arguments.

list-commitment-offerings

Purpose: What AWS sells for a Reserved Instance or Savings Plan the organization does not hold yet, one field at a time.

Returns: choices: for every field of the target, the values sold given every field before it, in the order each narrows the next. A reservation's fields are service, region, engine, deployment, offering_class, tenancy and resource; a plan's are plan_type, instance_family and region. A field with no choices does not apply and is left out. complete says the target is whole, and offers then lists every offering sold for it: offering_id, resource, term_months, payment_option, currency, upfront and recurring_hourly per unit (a reservation, or a dollar an hour of a plan), term_total, effective_hourly, and the public on-demand rate where the price list has one. Regions are where the organization's accounts live, hold commitments or run anything. fetched_at says when AWS was read; every page is kept a day. Buys nothing. AWS only.

When to use: Building a purchase by hand, including for infrastructure that does not run yet: call it field by field until complete, then quote the offer with preview-commitment-purchase and raise it with create-commitment-purchase, both passing its offering_id in new_purchase.

NOT for: What LevelFour recommends buying, which get-commitment-purchase-plan sizes. Renewing a commitment already held, which get-commitment-renewal-options prices.

Parameters

list-commitments

Purpose: The individual Reserved Instances and Savings Plans, and what each one costs.

Returns: each commitment with its kind, service, term, monthly fee, the account holding it against the accounts consuming it, and the instant it ends rather than the day. Totals come with it. A commitment is held on a payer and consumed elsewhere, so the holder answering for an account that looks uncovered is the normal case, not an error.

When to use: "What do we hold and what does it cost", or "what expires before the quarter ends" and sizing the cliff when that usage reverts to on-demand rates.

NOT for: Coverage or utilization, which are separate questions with separate denominators: get-commitment-coverage and get-commitment-utilization.

Parameters

list-cost-alert-events

Purpose: What one cost alert has said over time, newest first.

Returns: one entry per firing and per recovery, with the day it was about, the figure observed, the line it crossed and the cost basis it was measured on.

When to use: Settling whether a threshold is set well: a rule that fired eleven times last month is set too tight, and this is the only place that is visible.

NOT for: The current state, which list-cost-alerts carries.

Parameters

list-cost-alerts

Purpose: The organization's cost alerts and whether any is firing right now.

Returns: each rule with what it watches, its thresholds, where it goes, and the live state of every thing it watches.

When to use: "Are we over budget", "what are we being alerted on", or before proposing a new alert, so an existing one is changed with update-cost-alert rather than duplicated.

NOT for: What spend actually is, use get-cost-summary.

Parameters

Takes no arguments.

list-recommendations

Purpose: Savings opportunities LevelFour has found, largest first.

Returns: a paginated list with id, service, environment, account, monthly savings, the share of current spend that saves, display_status, risk level, how many resources it touches (resource_count, null when not itemised) and a short description. Only open opportunities unless display_status says otherwise, and the filter applied is echoed back as filtered_to. Read display_status: it is the word every LevelFour surface prints for a recommendation. status carries the same value here and is kept only for clients written before display_status existed. Full detail, annual figures included, is deliberately omitted: open one with get-recommendation. With group_by, returns totals per value of that dimension instead of the list, with no pages to walk. A row whose resources carry virtual tags lists them in virtual_tags, key name to value.

When to use: "What can we save." Filter server-side rather than paging and discarding: to answer "what can we save on RDS in staging", pass service and environment. service here is spelled the short way, ElastiCache or RDS, not the billing name the cost tools return, so a service copied out of get-cost-breakdown ("Amazon ElastiCache", "Amazon Relational Database Service") matches nothing and comes back as an empty page that reads like an empty backlog. When a spelling is in doubt, drop the filter and read service off the rows. For "which service holds the most" or any per-team or per-account split, pass group_by rather than paging the backlog and adding it up. For one team on a virtual tag, pass virtual_tag_key and virtual_tag_value.

Examples: biggest open wins: no arguments. Where the savings are concentrated: group_by="service". Everything actionable without a human: available_formats=["automated"]. What has already been applied: display_status=["optimized"]. What failed to apply: display_status=["failed"].

NOT for: Savings already realized, use get-savings-realized. These are potential and unbooked, and the two must never be added together.

Parameters

list-repositories

Purpose: The organizations and repositories a savings can open its pull request against.

Returns: called bare, the version control installations this organization has. Called with one, the repositories that installation can reach, narrowed by query when given.

When to use: Before set-implementation-method on a format that opens a pull request, to put the orgs and then the repositories in front of the user so they can choose. An organization can have thousands of repositories, so search rather than page: query matches any part of the name, and "postgres" or the resource in the recommendation is usually enough.

NOT for: Connecting an organization that has none, which is connect-version-control. Whether a savings already has a repository, which get-savings-readiness answers as a yes or no without naming it.

Parameters

pause-cost-alert

Purpose: Silence a cost alert, or arm one that was silenced.

Returns: the rule, with who paused it.

When to use: A rule that is firing on known, accepted spend. Pausing is reversible and the list says who did it.

NOT for: Removing a rule for good, which delete-cost-alert does, taking the rule's history with it.

Parameters

preview-commitment-purchase

Purpose: What one Savings Plan commitment, or one Reserved Instance or Savings Plan built by hand, would have done over the recent bill, before anything is bought.

Returns: the commitment replayed day by day over the payer's last complete days of the daily bill: eligible on-demand spend covered and left uncovered, commitment used and left unused, utilization, coverage and monthly savings, net_savings_monthly at public prices and net_savings_monthly_at_your_rates after the negotiated discount. Also a curve of the same at other commitments, the three sized profiles, and AWS's own figure with the gap to ours. The grain is daily and the source is the billing export: a day averages its hours, so every figure is an upper bound on the hourly truth, and the answer should say so. Nothing is bought or raised. unavailable_reason says why nothing could be replayed. AWS only. With new_purchase instead of plan_type and commitment_hourly, it quotes that purchase on its own term and payment: basis usage when the buying account's payer already runs the target, replayed day by day in units of what is bought, or full_use (every hour used, at the public on-demand rate, and at face with no saving claimed where there is none) when nothing runs there yet. It answers upfront, recurring_monthly, commitment_monthly and term_total at list price, the covered, left and unused spend, net_savings_monthly, savings_pct, coverage before and after, utilization, break_even_months, over_automation_cap (Automated Savings would refuse the term total; Manual Setup would not) and the daily series.

When to use: "What if we committed $10 an hour to a Compute Savings Plan", checking a size before proposing it, or pricing an offer from list-commitment-offerings.

NOT for: Which size to buy, which get-commitment-purchase-plan proposes. Renewing something that is expiring, use get-commitment-renewal-options.

Parameters

preview-virtual-tag

Purpose: Try a virtual tag's rules over real spend without saving anything.

Returns: spend, resource count and sample resources per value the rules would assign, unallocated_spend for the cost no rule matched, and shadowed_spend for the cost a later config matches but an earlier one already took. The window is at most 31 days.

When to use: Before create-virtual-tag, to check a draft assigns what the user meant, or to answer "what would a tag that does this show".

Examples: Redshift and BigQuery spend as data: one config whose filter has a rule for aws and gcp with the condition service is Amazon Redshift or BigQuery, assigning the value data.

NOT for: A tag that already exists, use get-tag. Nothing is stored, so a preview never changes a report.

Parameters

release-rollout

Purpose: Release a rollout a colleague asked for, as the admin answering them.

Returns: the decision as recorded, and the delivery format it was released with.

When to use: When the user names a rollout a colleague asked for and says to let it through. This is the release itself, so reach for it once they have said yes rather than to show them what is pending.

NOT for: Seeing what is waiting, which is list-approval-requests. Refusing one, which is decide-recommendation with decision='rejected'. Nor accepting a savings nobody has asked to roll out, which is decide-recommendation as well. Releasing needs a credential an organization admin authorized; a plain API key is refused.

Parameters

set-implementation-method

Purpose: Record how an accepted savings should be delivered, and for a pull request, where it lands.

Returns: the recommendation with the format now settled on it, the repositories it will open against, and whether that format can run yet.

When to use: When the user has told you which format they want. Only the formats in available_methods are accepted, so read those from get-recommendation if you do not already have them. 'iac' and 'one-click-plus-iac' open a pull request, so they also need the organization and the repositories the user chose, from list-repositories. Ask them; a repository is somebody's infrastructure and the customer is the only one who knows which holds this resource.

NOT for: Starting the rollout, which is start-rollout. Changing the format once a rollout has begun, which is refused here: the steps already recorded belong to the old format. Choosing 'manual' says the customer will apply the change themselves, and get-manual-instructions is what they follow next.

Parameters

start-rollout

Purpose: Put an accepted savings into the rollout queue.

Returns: either that the rollout started, or that an approval request was filed for an admin to release, in outcome. Which of the two happens depends on the credential: one an admin authorized starts it, any other files the request the way a team member's click does. A new Reserved Instance or Savings Plan purchase (BUY-) started with Automated Savings then waits up to 24 hours before it is sent to AWS, so an admin can still buy it now or cancel it from the LevelFour dashboard; say so rather than reporting it bought.

When to use: When the user says to go ahead on a savings that is already accepted and already has its delivery format settled, its destination included.

NOT for: Accepting it, which is decide-recommendation and has to happen first. Not for the manual format either: nothing is queued for a change the customer applies themselves, and get-manual-instructions is what they need instead. Nor for a format that cannot run yet: Automated Savings needs a scoped grant the customer launches in their AWS console, and IaC needs a bound repository. Both are refused here and both are finished in the LevelFour dashboard, so pass the refusal on rather than trying another way. A credential an administrator authorized may start a savings it also accepted, which is one click of Approve Savings; any other credential files an approval request for somebody else to answer, and that refusal is not something to work around.

Parameters

update-anomaly-status

Purpose: Record what the user decided about one detected cost anomaly.

Returns: the anomaly id and the status now recorded against it.

When to use: Only when the user has told you, in this conversation, what to do with a specific anomaly. "That spike was our migration" is planned. "That was not real" is dismissed. "We fixed it" is resolved.

NOT for: Changing any cloud spend. This writes a status on a LevelFour row and nothing else. Dismissing also trains the detector, so do not use it to tidy a list. To read anomalies rather than judge them, use list-anomalies. Read status in the result rather than assuming your argument was stored verbatim. 'acknowledged', 'planned' and 'resolved' all store resolved and differ in the feedback recorded, so the row will not read back as 'acknowledged'.

Parameters

update-commitment-purchase

Purpose: Re-size a purchase nobody has decided yet: a Savings Plan on today's proposal, or a purchase raised on terms of the user's own. It buys nothing.

Returns: the same fields as create-commitment-purchase, with rebound true and the same id. Naming neither profile nor commitment_hourly re-sizes the pick it was raised on against the latest daily bill. A purchase raised with new_purchase takes a new_purchase again: its size, term, payment and offering may change, its target and buying account may not.

When to use: The user wants another size, term or offering for a purchase already raised, or the proposal moved since it was raised.

NOT for: A purchase anybody already accepted, rejected or requested, which is refused: reject it with decide-recommendation and raise again with create-commitment-purchase.

Parameters

update-cost-alert

Purpose: Change a cost alert: its name, what it watches, its rule, or where it goes.

Returns: the stored rule as it now reads.

When to use: Raising or lowering a threshold, moving a rule to another account or cost view, or changing who hears about it. Only what is passed changes. Read the rule with list-cost-alerts first, because a changed params replaces the whole rule.

NOT for: Silencing a rule, which pause-cost-alert does and the list then says who did.

Parameters

update-virtual-tag

Purpose: Replace an existing virtual tag's whole definition.

Returns: the tag as get-tag reads it, with the reprocessing job.

When to use: Only when the user asked, in this conversation, for a tag to be changed. Read it with get-tag, edit its definition, and send the whole definition back with the expected_version it reported. Anything you leave out is cleared rather than kept, because this replaces rather than patches.

NOT for: Defining a tag that does not exist yet, use create-virtual-tag. Provider tags, which are read from the bill and never modified.

Parameters

update-virtual-tag-config

Purpose: Replace one config of a virtual tag, leaving the rest of it alone.

Returns: the tag as get-tag reads it, with the reprocessing job.

When to use: Changing what one value matches. This replaces that one config whole, so send its filter and assign together even when only one of them changes, and the config keeps its place in the order.

NOT for: Changing the tag's name, description or backfill month, use update-virtual-tag. Moving a config, use update-virtual-tag-config-order.

Parameters

update-virtual-tag-config-order

Purpose: Move one config of a virtual tag to another place in the order.

Returns: the tag as get-tag reads it, with the reprocessing job.

When to use: Order is precedence: the first config whose filter matches a line assigns it, so a config sitting below a broader one never fires. Move it above that one. This is also the fix after create-virtual-tag-config, which always appends last.

NOT for: Changing what a config matches, use update-virtual-tag-config.

Parameters