> ## Documentation Index > Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt > Use this file to discover all available pages before exploring further. # List virtual machines > Returns virtual machine metadata for the tenant selected by the X-CostGraph-Tenant-ID header ## OpenAPI ````yaml /api-reference/costgraph/openapi.json get /api/v1/tenant/virtual-machines openapi: 3.0.0 info: description: Read and manage your CostGraph organization, spend, alerts, and settings. title: CostGraph API contact: {} version: '1.0' servers: - url: https://api.costgraph.ai security: [] tags: - name: ai x-group: AI - name: ai-serving x-group: AI serving - name: anomalies x-group: Anomalies - name: auth x-group: Auth - name: billing x-group: Billing - name: billing-export x-group: Billing export - name: budgets x-group: Budgets - name: ci x-group: CI - name: compute-recommendations x-group: Compute recommendations - name: config x-group: Config - name: cost x-group: Cost - name: gpus x-group: GPUs - name: graphai x-group: Graph AI - name: infracost x-group: Infracost - name: integrations x-group: Integrations - name: invitations x-group: Invitations - name: kubernetes-clusters x-group: Kubernetes clusters - name: marketplace x-group: Marketplace - name: network-requests x-group: Network requests - name: notifications x-group: Notifications - name: oauth x-group: OAuth - name: oauth-clients x-group: OAuth clients - name: opencost x-group: OpenCost - name: organization x-group: Audit log - name: organizations x-group: Organizations - name: placement-alternatives x-group: Placement alternatives - name: reports x-group: Reports - name: service-map x-group: Service map - name: settings x-group: Settings - name: sso x-group: Single sign-on - name: tenants x-group: Tenants - name: user x-group: Users - name: virtual-machines x-group: Virtual machines - name: virtual-tags x-group: Virtual tags - name: workflows x-group: Workflows paths: /api/v1/tenant/virtual-machines: get: tags: - virtual-machines summary: List virtual machines description: >- Returns virtual machine metadata for the tenant selected by the X-CostGraph-Tenant-ID header parameters: - description: Tenant ID name: X-CostGraph-Tenant-ID in: header required: true schema: type: string - description: Filter by cloud provider (repeat param or comma-separated) name: provider in: query style: form explode: false schema: type: array items: type: string - description: Filter by region (repeat param or comma-separated) name: region in: query style: form explode: false schema: type: array items: type: string - description: Filter by availability zone (repeat param or comma-separated) name: availability_zone in: query style: form explode: false schema: type: array items: type: string - description: Filter by instance type (repeat param or comma-separated) name: instance_type in: query style: form explode: false schema: type: array items: type: string - description: Filter by architecture (repeat param or comma-separated) name: architecture in: query style: form explode: false schema: type: array items: type: string - description: Filter by operating system (repeat param or comma-separated) name: operating_system in: query style: form explode: false schema: type: array items: type: string - description: Filter by active heartbeat state name: active in: query schema: type: boolean - description: Search by VM name or hostname name: search in: query schema: type: string - description: Number of rows to return (default 50, max 200) name: limit in: query schema: type: integer - description: Rows to skip before returning results (default 0) name: offset in: query schema: type: integer - description: >- Sort field and direction. Prefix with - for descending order. Available values: name, provider, region, availability_zone, instance_type, usage_type, operating_system, cpu_cores, ram_gb, cost.mtd, cost.projected_monthly_spend, cost.change_percent, cpu_utilization_percent, memory_utilization_percent, recommendation.savings_monthly_usd name: sort in: query schema: type: string responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/responses.SuccessResponse' - type: object properties: data: $ref: >- #/components/schemas/costgraph_agent.VirtualMachineListResult '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' security: - BearerAuth: [] components: schemas: responses.SuccessResponse: type: object required: - message - status properties: data: {} message: type: string example: some message status: type: string example: success costgraph_agent.VirtualMachineListResult: type: object required: - items - limit - offset - total_count properties: items: description: |- Page of VMs matching the request's filters, in the requested sort order. Empty when no VM matches. type: array items: $ref: '#/components/schemas/costgraph_agent.VirtualMachineMetadata' limit: description: Page size that was applied to this result. type: integer offset: description: |- Number of matching VMs skipped before Items, per the request's pagination. type: integer total_count: description: Total number of VMs matching the filters, across all pages. type: integer responses.ErrorResponse: type: object required: - message - status properties: message: type: string example: some message status: type: string example: error costgraph_agent.VirtualMachineMetadata: type: object required: - active - availability_zone - cost - cpu_utilization_sparkline - created_at - hostname - id - instance_type - last_heartbeat_at - memory_utilization_sparkline - name - provider - recommendation_state - region - status - usage_type properties: active: description: |- Whether the VM is currently running (as opposed to stopped or terminated). type: boolean assigned_price: $ref: '#/components/schemas/costgraph_agent.ComputePrice' availability_zone: description: |- Provider availability zone within Region, as reported by the provider, e.g. AWS-style "us-east-1a". Format varies by provider. type: string cost: description: Cost figures for this VM in the current billing period. allOf: - $ref: '#/components/schemas/costgraph_agent.VirtualMachineCost' x-nullable: 'false' cpu_utilization_percent: description: >- Most recent CPU utilization sample, as a percent (0-100). Nil when no utilization sample has been collected yet. type: number x-semantic: percentage nullable: true cpu_utilization_sparkline: description: |- CPUUtilizationSparkline is the trailing 24h of CPU utilization in 12 fixed-width 2h buckets, oldest first; each bucket is max_over_time (percent, 0-100). Nil entries mark buckets with no sample. type: array items: type: number created_at: description: When CostGraph first observed this VM. type: string hostname: description: >- OS-level hostname reported by the monitoring agent running on the VM. type: string id: description: Provider-agnostic identifier CostGraph assigned to this VM. type: string x-semantic: resourceId instance_type: description: |- Provider instance type SKU, as reported by the provider, e.g. AWS-style "m5.large". Format varies by provider. type: string last_heartbeat_at: description: |- Timestamp of the most recent heartbeat received from the monitoring agent running on this VM. type: string memory_utilization_percent: description: >- Most recent memory utilization sample, as a percent (0-100). Nil when no utilization sample has been collected yet. type: number x-semantic: percentage nullable: true memory_utilization_sparkline: description: >- MemoryUtilizationSparkline has the same shape as CPUUtilizationSparkline. type: array items: type: number name: description: Display name of the VM, as reported by the provider or the agent. type: string provider: description: Cloud provider hosting the VM, e.g. "aws", "gcp", "azure". type: string recommendation: description: >- Rightsizing recommendation for this VM. Nil unless RecommendationState is "actionable". allOf: - $ref: >- #/components/schemas/costgraph_agent.VirtualMachineRecommendation nullable: true recommendation_state: description: Lifecycle stage of the rightsizing analysis for this VM. type: string enum: - pending_first_run - insufficient_signal - right_sized - actionable - unavailable region: description: |- Provider region the VM runs in, as reported by the provider, e.g. AWS-style "us-east-1". Format varies by provider. type: string status: description: Monitoring agent's connectivity state for this VM. type: string enum: - healthy - offline - unknown usage_type: description: |- Billing purchase-option the VM is running under, e.g. "ONDEMAND", "RESERVED", "SPOT_PREEMPTIBLE". type: string costgraph_agent.ComputePrice: type: object required: - assigned_resources - cost_per_hour - cpu_cores - currency - id - instance_type - ram_gb - region - usage_type properties: assigned_resources: type: integer cost_per_hour: type: number cpu_cores: type: number currency: type: string gpu_count: type: number gpu_type: type: string id: type: string x-semantic: resourceId instance_type: type: string ram_gb: type: number region: type: string usage_type: type: string costgraph_agent.VirtualMachineCost: type: object required: - mtd - projected_monthly_spend - runtime_hours properties: change_percent: description: >- Signed percent change of MTD against the same VM's MTD in the previous comparable period. Nil when there is no previous-period cost to compare against. type: number x-semantic: percentage nullable: true mtd: description: >- Spend accrued from the start of the billing month through now, in the tenant's billing currency. type: number x-semantic: costAmount projected_monthly_spend: description: |- MTD extrapolated to a full calendar month at the current run rate, same currency. type: number x-semantic: costAmount runtime_hours: description: Hours the VM has been running within the current billing month. type: number costgraph_agent.VirtualMachineRecommendation: type: object required: - action - generated_at properties: action: description: Rightsizing action the recommendation engine suggests. type: string enum: - UPSIZE - DOWNSIZE - TERMINATE confidence: description: |- How confident the engine is in this recommendation. Absent when confidence was not assessed. type: string enum: - low - medium - high generated_at: description: When the recommendation engine last produced this recommendation. type: string recommended_instance_type: description: Instance type SKU to move to. Empty when Action is TERMINATE. type: string savings_monthly_usd: description: |- Estimated monthly savings in USD from applying the recommendation. Nil when a savings estimate could not be computed. type: number x-semantic: costAmount nullable: true securitySchemes: BearerAuth: description: Enter "Bearer {token}" type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.