> ## 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. # Explain virtual machine spend change > Returns the events most responsible for the period-over-period change in VM spend (VMs added/removed, compute/storage shifts). Filters mirror /summary. ## OpenAPI ````yaml /api-reference/costgraph/openapi.json get /api/v1/tenant/virtual-machines/summary/explain 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/summary/explain: get: tags: - virtual-machines summary: Explain virtual machine spend change description: >- Returns the events most responsible for the period-over-period change in VM spend (VMs added/removed, compute/storage shifts). Filters mirror /summary. 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: >- Cost period: month_to_date, last_7d, last_30d, calendar_month, or custom name: period in: query schema: type: string - description: >- Closed calendar month in YYYY-MM format; required when period=calendar_month name: month in: query schema: type: string - description: >- Custom period start timestamp in RFC3339 format; required when period=custom name: start in: query schema: type: string - description: >- Custom period end timestamp in RFC3339 format; required when period=custom name: end 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.VirtualMachineSpendChangeExplanation '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.VirtualMachineSpendChangeExplanation: type: object required: - change_amount - contributors - currency - current_cost - movers - period - period_end - period_start - previous_cost - previous_period_end - previous_period_start properties: change_amount: description: Signed absolute change of CurrentCost against PreviousCost. type: number x-semantic: costAmount change_percent: description: |- Signed percent change of CurrentCost against PreviousCost. Nil when PreviousCost is zero. A small nonzero value is floored to 0.001 in magnitude, so it never rounds away to a visible zero. type: number x-semantic: percentage nullable: true contributors: description: |- Groups of VMs that explain ChangeAmount, sorted by absolute ChangeAmount descending. Empty when no contributor cleared the noise floor. type: array items: $ref: >- #/components/schemas/costgraph_agent.VirtualMachineSpendChangeContributor currency: description: |- Currency code all monetary fields in this explanation are expressed in, matching the tenant's billing currency. type: string x-semantic: currencyCode current_cost: description: Total VM spend in the current period. type: number x-semantic: costAmount movers: description: >- Individual VMs flattened out of Contributors' TopResources (or the sample VM when a contributor has no drill-down), one entry per VM. A VM that moved in more than one contributor - compute_changed and storage_changed both name VMs present in each period - is merged into a single entry with its amounts summed, so an id never repeats. Ordered by first appearance in Contributors, not by Amount. Empty when Contributors is empty. type: array items: $ref: >- #/components/schemas/costgraph_agent.VirtualMachineSpendChangeMover period: description: Label for the reporting period this explanation covers, e.g. "mtd". type: string period_end: description: End of the current period, exclusive. type: string period_start: description: Start of the current period, inclusive. type: string previous_cost: description: Total VM spend in the previous period. type: number x-semantic: costAmount previous_period_end: description: End of the comparable previous period, exclusive. type: string previous_period_start: description: Start of the comparable previous period, inclusive. type: string responses.ErrorResponse: type: object required: - message - status properties: message: type: string example: some message status: type: string example: error costgraph_agent.VirtualMachineSpendChangeContributor: type: object required: - change_amount - kind - vm_count properties: change_amount: description: |- Combined signed change in spend across all VMs folded into this contributor, in the explanation's Currency. type: number x-semantic: costAmount event_at: description: >- EventAt is the sample resource's first-active timestamp for additions, last active_until for removals, otherwise nil. type: string instance_type: description: |- Instance type shared by every VM in this contributor. Nil when the contributor groups VMs of mixed instance types. type: string kind: description: |- Kind classifies the contributor: "vms_added" — VMs with no prev-period cost that ran in current. "vms_removed" — VMs with prev-period cost that did not run in current. "compute_changed" — VMs present in both periods whose compute spend moved. "storage_changed" — VMs present in both periods whose storage spend moved. type: string provider: description: |- Provider shared by every VM in this contributor. Nil when the contributor groups VMs across providers. type: string region: description: |- Region shared by every VM in this contributor. Nil when the contributor groups VMs across regions. type: string sample_change_amount: description: |- Signed change in spend attributable to the VM identified by SampleResourceID, in the explanation's Currency. Nil under the same condition as SampleResourceID. type: number x-semantic: costAmount sample_resource_id: description: |- Identifier of one representative VM from this contributor, used when TopResources is empty. Nil when no representative VM was retained. type: string x-semantic: resourceId sample_resource_name: description: |- Display name of the VM identified by SampleResourceID. Nil under the same condition as SampleResourceID. type: string top_resources: description: >- Largest individual VMs behind this contributor's ChangeAmount, sorted by absolute change descending. Empty when the contributor represents a single VM, in which case use the Sample* fields instead. type: array items: $ref: >- #/components/schemas/costgraph_agent.VirtualMachineSpendChangeTopResource vm_count: description: Number of distinct VMs folded into this contributor. type: integer costgraph_agent.VirtualMachineSpendChangeMover: type: object required: - amount - id - name properties: amount: description: |- Signed change in this VM's spend between the previous and current period, in the explanation's Currency. type: number x-semantic: costAmount id: description: |- Provider-agnostic identifier of the VM. Empty when the underlying contributor recorded no representative VM identifier. type: string x-semantic: resourceId name: description: Display name of the VM. Empty under the same condition as ID. type: string costgraph_agent.VirtualMachineSpendChangeTopResource: type: object required: - change_amount - resource_id - resource_name properties: change_amount: description: |- Signed change in this VM's spend between the previous and current period, in the explanation's Currency. type: number x-semantic: costAmount resource_id: description: Provider-agnostic identifier of the VM behind this line item. type: string x-semantic: resourceId resource_name: description: Display name of the VM. type: string 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.