run_query
Run custom analytics queries across cloud providers to analyze costs, generate breakdowns, and view spending trends.
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. |