Metrics Endpoints

Endpoints are under /v1/metrics.

Base URL: https://api.gpcn.com/v1

See the API Reference → for examples in TypeScript, Python, Go, and C#.

VM Metrics

GET /metrics/virtual-machines

Returns VM metrics with hierarchical breakdown by category, tier, region, and data center. Supports period comparison for trend analysis.

Parameter	Type	Default	Description
`currentPeriodStart`	ISO 8601	Start of current month	Period start date
`currentPeriodEnd`	ISO 8601	Now	Period end date
`comparisonPeriodStart`	ISO 8601	—	Comparison period start
`comparisonPeriodEnd`	ISO 8601	—	Comparison period end
`categories`	string	—	Filter by category codes (e.g., `"general"`, `"gpu"`)
`datacenters`	UUID[]	—	Filter by data center IDs
`includeVmNames`	boolean	`false`	Include individual VM names in response

curl "https://api.gpcn.com/v1/metrics/virtual-machines?currentPeriodStart=2026-03-01" \
  -H "X-API-Key: gpcn_your_api_key_here"

Hierarchical structure with summary, categories, tiers, regions, data centers, VM counts, specs, and trends (up/down/stable).

GET /metrics/entity/{id}/usage

Returns VM usage statistics for a specific entity (organization), broken down by size category and region.

Parameter	Type	Description
`id`	UUID	Entity ID

Parameter	Type	Default	Description
`month`	string	Current month	Month in `YYYY-MM` format. Cannot be a future month.

Summary totals with breakdown by VM size category and region for the requested month.

GET /metrics/entity/{id}/available-months

Returns which months have usage data available for an entity.

Parameter	Type	Description
`id`	UUID	Entity ID

{
  "success": true,
  "data": ["2026-02", "2026-01", "2025-12", "2025-11"]
}

Array of YYYY-MM strings ordered most recent first. Covers the last 24 months.