run_query
Analyze cloud costs, generate cost breakdowns, and view spending trends by running custom analytics queries across your cloud providers.
Instructions
Use this when the user wants to analyze cloud costs, generate a cost breakdown, view spending trends, or run a custom analytics query across their cloud providers. Accepts a structured config with data source, metrics, dimensions, time range, and filters. Do NOT use this for listing saved reports (use list_reports), checking anomalies (use get_anomalies), or viewing budgets (use list_budgets).
Fields that are not populated will use their default values if needed.
To limit the number of rows returned per group, set the limit.value field inside each config.group[] entry (maximum 25).
If possible, use timeRange instead of customTimeRange when no specific dates are given.
Use "includeCurrent": true to include the current in-progress month. Use "includeCurrent": false only when asking about a fully completed past period.
Always use "metrics" (array) not the deprecated "metric" (object).
ALWAYS include a "group" with id "service_description" and type "fixed" unless the user explicitly asks to group by something else. This gives a per-service cost breakdown which is always the most useful default.
Common grouping dimension IDs (all type "fixed"):
"service_description" — cloud service (default)
"project_id" — GCP project / AWS account / Azure subscription (use when user asks to group by project, account, or subscription)
"cloud_provider" — cloud provider (AWS / GCP / Azure)
IMPORTANT — filter values are dimension IDs, never display names. Before filtering on any dimension
you are unsure about, call get_dimension({type, id}) to retrieve the exact valid values for this customer.
Known cloud provider IDs (cloud_provider, type "fixed"):
"amazon-web-services" = AWS, "google-cloud" = GCP, "microsoft-azure" = Azure
Example — top AWS services last month:
{
"config": {
"dataSource": "billing",
"metrics": [{"type": "basic", "value": "cost"}],
"timeRange": {"mode": "last", "amount": 1, "unit": "month", "includeCurrent": true},
"filters": [{"id": "cloud_provider", "type": "fixed", "values": ["amazon-web-services"]}],
"group": [{"id": "service_description", "type": "fixed", "limit": {"metric": {"type": "basic", "value": "cost"}, "sort": "desc", "value": 10}}]
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| config | Yes | Configuration for the query. Use the dimension tool to look up valid dimension IDs. |