Actions Reference
The server exposes four tools and 35 read-only actions. You never name an action yourself. You ask a question, the assistant calls search_actions to find the right one, then execute_action to run it. This page exists so you know what is reachable and can phrase questions that land.
Every action is read-only. Nothing here creates, edits or deletes.
The four tools
| Tool | Purpose |
|---|---|
search_actions(query, category?, limit?) | Find an action by natural-language query. Returns its id and parameter schema. |
execute_action(id, path_params?, query_params?, body?) | Run an action. Returns { status, ok, body }. |
list_categories() | Counts per category, the API base URL, and which auth source is in use. |
login() | Browser-based CloudYali sign-in. |
Cost (5 actions)
| Action | Answers |
|---|---|
cost.report | A cost report as a chart or a table, across cloud providers. |
cost.aggregate | Costs grouped by dimensions, optionally bucketed by time interval. |
cost.spend | Total spend, with period-over-period comparison. |
cost.filters | Which filter values actually exist: accounts, regions, services, tags. |
cost.filter_parameters_for_budgets | The filter parameters the Budgets feature uses. |
Ask things like:
- "Break down last month's AWS bill by service."
- "Show daily GCP spend for June as a chart."
- "Compare this month's total spend to last month. What changed?"
cost.filters is the one to reach for when you are unsure what a filter value should be. Asking the assistant to "list the available filters first" is usually faster than guessing at an account alias or service name.
Budgets (7 actions)
| Action | Answers |
|---|---|
budgets.list | Every budget for your account. |
budgets.summary | Aggregate metrics across all budgets. |
budgets.get | One budget, by numeric id. |
budgets.resources | Which resources drove a budget's spend in a date range. |
budgets.history | Spend against budget over time. |
budgets.config_history | How a budget's configuration has changed. |
budgets.alert_history | When a budget's alerts have fired. |
Ask things like:
- "How are we tracking against our budgets?"
- "Which resources drove the production budget's spend in June?"
- "Has the data-transfer budget fired any alerts in the last month?"
Reads only. Creating, editing and deleting budgets stay in the portal, by a human.
Savings recommendations (7 actions)
| Action | Answers |
|---|---|
recommendations.list | Recommendations, with filters. |
recommendations.summary | Totals and the savings rollup. |
recommendations.filter_options | Valid filter values for listing. |
recommendations.top_savings | The top N by potential savings. |
recommendations.get | One recommendation, by numeric id. |
recommendations.history | How a recommendation's status has changed. |
recommendations.users | Users available for assignment. |
Ask things like:
- "What are our top savings opportunities right now?"
- "List open recommendations for EBS volumes with more than $50/month savings."
- "How much could we save in total if we actioned every recommendation?"
- "Group open recommendations by how hard they are, not how much they save."
That last one is worth knowing about. The console ranks by savings, which is the right default. An assistant holding the rows can re-rank them by whatever matters to you this week.
Anomalies (4 actions)
| Action | Answers |
|---|---|
anomalies.list | Anomalies, paginated and filterable. |
anomalies.summary | Dashboard summary statistics. |
anomalies.get | One anomaly, by UUID. |
anomalies.preferences_get | Your anomaly alert preferences. |
Ask things like:
- "Any cost anomalies in the last seven days?"
- "Summarize anomaly count and impact for the quarter."
- "Show the root cause breakdown for anomaly
<id>."
Asset inventory (12 actions)
Inventory is the largest category, because questions about which resources exist, where they run, how they are tagged and what they cost turn out to be a large share of real FinOps work.
| Action | Answers |
|---|---|
inventory.list | Resources across clouds, with filters. |
inventory.search | Free-text search across all resources. |
inventory.get | One resource, by its cloud-native id. |
inventory.stats | Resource counts by provider and type. |
inventory.resource_costs | Cost data for specific resources. |
inventory.history | Configuration change history for a resource. |
inventory.tag_keys | Distinct tag keys across all resources. |
inventory.tag_values | Distinct values for a given tag key. |
inventory.providers | Cloud providers present in inventory. |
inventory.types | Resource types, with display names. |
inventory.regions | Regions, with display names. |
inventory.accounts | Accounts, subscriptions and projects. |
Ask things like:
- "How many EC2 instances do we have, per region?"
- "Find all resources tagged environment=prod that are still active."
- "Search inventory for anything named 'prod-web'."
- "What did instance i-0abc123 cost last month?"
- "What changed on this security group's configuration recently?"
The five lookup actions (tag_keys, tag_values, providers, types, regions, accounts) exist so the assistant can find out what values are legal before filtering on them. You rarely ask for these directly; the assistant reaches for them on its own.
Prompting guidance
Name a date range when you care about one. Otherwise a sensible default applies, usually the last 30 to 90 days. Most surprising numbers trace back to an unstated period.
Name the cloud provider if you want just one. Otherwise you get everything, which is often what you want and occasionally not.
Ask for the filters first when you are unsure. "List the available filters, then show me spend for the production account" is more reliable than guessing at the account's exact name.
Ask for an artefact, not just a figure. The assistant is holding the rows, so "build me a month-end review I can send to the leadership team" is a reasonable request, not a stretch.
Chain the follow-up. The assistant keeps its place across a conversation, so "okay, which accounts, and do we have open recommendations against them?" works and spans two data domains.
Two cautions
An empty result is not proof of zero spend. A filter that matched nothing and a period with genuinely no cost look identical in a chat reply. If a zero is surprising, ask which filters were applied.
Spot-check anything you will quote to someone else. The underlying data is identical to what the console shows. The assistant's choices of grouping, date range and cost types may not match the view you had in mind.
Adding actions
The catalog lives in src/catalog.ts in the open-source repository. New actions must be read-only and carry a test. Because discovery is dynamic, CloudYali can add actions without any change on your side.