> ## Documentation Index > Fetch the complete documentation index at: https://docs.playflowcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Get server resource metrics > Returns CPU, memory, network, load, and connection metrics for a running server over a configurable time window. Each metric is a time series of `{t, v}` data points where `t` is a Unix timestamp and `v` is the metric value. Use `period` to control the time window (e.g., `1h` for last hour) and `step` for data point resolution (e.g., `60s` for one point per minute). Only available for servers that are currently running. ## OpenAPI ````yaml https://api.computeflow.cloud/api/doc get /api/v3/servers/{instance_id}/metrics openapi: 3.1.0 info: title: PlayFlow API version: 3.0.0 description: > PlayFlow is a game server hosting and orchestration platform. Deploy, manage, and scale multiplayer game servers globally with built-in matchmaking, lobby management, and billing. ## Authentication All API endpoints (except Health) require the `api-key` header: ``` api-key: pf_your_project_api_key ``` Find your API key in the PlayFlow dashboard under **Project Settings**. Each project has two keys, both sent in the `api-key` header: - **Server key** (`pf_...`) — full access. Keep it secret (server-side only). - **Client key** (`pfclient_...`) — safe to embed in shipped game clients. It has access to all player-facing lobby, matchmaking, and read endpoints, but is **rejected with `403`** from admin/privileged routes: admin lobby get/force-delete (`GET`/`DELETE /v3/lobbies/{config}/{id}`), build deletion (`DELETE /v3/builds/{id}`), and project settings (`POST /v3/projects/settings`). Server lifecycle mutations (start/stop/restart/update) are allowed for client keys by default but can be locked to server-key-only per project via the `client_key_server_control` setting. ## Quick Start 1. **Upload a build**: `POST /v3/builds/upload-url` → get presigned URL → `PUT` your ZIP → processing starts automatically 2. **Start a server**: `POST /v3/servers/start` → get connection info in `network_ports` 3. **Connect your game client**: Use `host:external_port` from the response ## Key Concepts - **Builds**: Your game server binary packaged as a ZIP or Docker image. Versioned per name per project. - **Servers**: Running game server instances. Each gets dedicated compute and network ports with automatic health monitoring. - **Pool Servers**: Pre-provisioned servers for instant startup (~5s vs ~30s cold start). - **Regions**: 13 global regions (us-east, us-south, us-west, eu-north, eu-west, eu-uk, ap-south, sea, ap-north, ap-southeast, south-africa, south-america-brazil, south-america-chile). - **Compute Sizes**: From micro (512MB) to dedicated-xlarge (16GB dedicated CPU). ## Server Lifecycle `launching` → `running` (game ports open) → `stopped` (game exits, TTL expires, or manual stop) ## Build Lifecycle `uploading` → `processing` (build pipeline creates deployable image) → `ready` | `failed` ## Rate Limits - General reads: 100 req/sec per API key - Write operations (start server, upload build): 10 req/sec per API key - Player-facing lobby writes (join, matchmaking, start): 10 req/sec **per player** (keyed by `x-player-id`), so a game's whole player base doesn't share one bucket - Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining` ## Plan Limits - **Free**: 1 server max, forced 1hr TTL, small size only - **Pro**: Unlimited servers, all sizes, custom TTL, pool servers ## Error Format All errors return: `{ "error": "message", "detail": "context", "status": 404 }` servers: - url: https://api.computeflow.cloud security: - ApiKeyAuth: [] tags: - name: Servers description: >- Create, manage, and monitor game server instances. Each server gets dedicated compute, network ports, and automatic health monitoring with TTL enforcement. Servers start in `launching` status and transition to `running` when the game opens its ports. - name: Builds description: >- Upload and manage game server builds. Supports ZIP uploads (automatically processed into deployable images) and direct Docker image references. Builds are versioned per name per project — uploading a new build with the same name auto-increments the version. Servers always use the latest `ready` build unless a specific version is pinned. - name: Projects description: >- Configure project-level settings including network ports, player authentication, environment variables, server pooling, and lobby/matchmaking rules. Settings apply as defaults to all servers in the project and can be overridden per-server at start time. - name: Lobbies description: >- Player-centric lobby and matchmaking system. Every request identifies the player via the `x-player-id` header. Use `/me` endpoints to interact with your current lobby — the API resolves which lobby you're in automatically. **Quick start:** `POST /v3/lobbies/default` creates a lobby with sensible defaults (no dashboard config needed). Share the invite `code` with friends, or use `POST /v3/lobbies/default/me/matchmaking` to find opponents automatically. **Matchmaking** supports symmetric teams (2v2, 5v5), asymmetric roles (1 monster vs 5 hunters), FFA, battle royale duos, and skill-based matching with auto-expanding MMR buckets. paths: /api/v3/servers/{instance_id}/metrics: get: tags: - Servers summary: Get server resource metrics description: >- Returns CPU, memory, network, load, and connection metrics for a running server over a configurable time window. Each metric is a time series of `{t, v}` data points where `t` is a Unix timestamp and `v` is the metric value. Use `period` to control the time window (e.g., `1h` for last hour) and `step` for data point resolution (e.g., `60s` for one point per minute). Only available for servers that are currently running. operationId: getServerMetrics parameters: - schema: type: string description: Server instance ID. required: true description: Server instance ID. name: instance_id in: path - schema: type: string enum: - 5m - 15m - 1h - 6h - 24h default: 1h description: >- Relative time window for metrics (used when start_time is omitted). "5m": last 5 minutes, "15m": last 15 minutes, "1h": last hour, "6h": last 6 hours, "24h": last 24 hours. required: false description: >- Relative time window for metrics (used when start_time is omitted). "5m": last 5 minutes, "15m": last 15 minutes, "1h": last hour, "6h": last 6 hours, "24h": last 24 hours. name: period in: query - schema: type: string enum: - 15s - 30s - 60s - 300s - 600s - 1800s default: 60s description: >- Data point interval. Smaller steps give higher resolution but more data. "15s": every 15 seconds … "1800s": every 30 minutes. Scale it to the window (a wide window needs a coarse step). required: false description: >- Data point interval. Smaller steps give higher resolution but more data. "15s": every 15 seconds … "1800s": every 30 minutes. Scale it to the window (a wide window needs a coarse step). name: step in: query - schema: type: string description: >- Absolute window start — ISO 8601 (e.g., "2026-07-12T03:00:00Z") or relative (e.g., "-6h"). When set it OVERRIDES period, so you can inspect a specific interval (pair with end_time). required: false description: >- Absolute window start — ISO 8601 (e.g., "2026-07-12T03:00:00Z") or relative (e.g., "-6h"). When set it OVERRIDES period, so you can inspect a specific interval (pair with end_time). name: start_time in: query - schema: type: string description: >- Absolute window end — ISO 8601. Defaults to now. Use with start_time for a fixed interval (e.g., a past incident window). required: false description: >- Absolute window end — ISO 8601. Defaults to now. Use with start_time for a fixed interval (e.g., a past incident window). name: end_time in: query responses: '200': description: Server resource metrics over the requested time window. content: application/json: schema: type: object properties: instance_id: type: string description: Server instance ID. machine_id: type: string description: Fly.io machine ID providing these metrics. region: type: string description: Fly.io region code (e.g., "ewr", "fra"). compute_size: type: - string - 'null' description: >- PlayFlow compute size of the machine (e.g. "small", "large"). vcpus: type: - number - 'null' description: >- Number of vCPUs allocated to the machine, derived from compute_size. Threshold the 1-minute load average against this: at/above vcpus is a warning, at/above 2× is an overload likely to freeze the game loop. Null when the size is unknown. lifecycle: type: object properties: started_at: type: - string - 'null' description: >- ISO 8601 time the current run started (last launch/restart). Overlay as a reference line so restarts are visible on the metric charts. stopped_at: type: - string - 'null' description: >- ISO 8601 time the server stopped, or null if still running. shutdown_reason: type: - string - 'null' description: >- Why the server stopped (e.g. "oom", "ttl", "crash", "user"). Pair with stopped_at to mark an OOM/crash line on the timeline. required: - started_at - stopped_at - shutdown_reason description: Restart/stop/OOM markers for the charts. period: type: object properties: start: type: number description: Unix timestamp for the start of the metrics window. end: type: number description: Unix timestamp for the end of the metrics window. step: type: string description: Data point interval used (e.g., "60s"). required: - start - end - step description: Time window and resolution for the returned metrics. cpu: type: object properties: usage_percent: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- CPU usage percentage over time (0–100+). Values above 100% indicate multiple cores being used. iowait_percent: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- Percentage of CPU time spent waiting on I/O. Sustained high iowait is a common cause of game-loop stalls/freezes (the process is blocked on disk or network). steal_percent: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- Percentage of CPU time "stolen" by the hypervisor for other tenants. Elevated steal indicates noisy-neighbor contention on the host and can cause hitches the game cannot control. required: - usage_percent description: >- CPU usage metrics, broken down to surface I/O-wait and steal which are typical freeze culprits. memory: type: object properties: used_mb: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Memory usage in megabytes over time. total_mb: type: number description: Total memory available to this machine in megabytes. required: - used_mb - total_mb description: Memory usage metrics. network: type: object properties: rx_bytes_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Inbound network throughput in bytes per second. tx_bytes_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Outbound network throughput in bytes per second. rx_packets_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- Inbound packets per second. Packet rate (vs. byte rate) better reflects per-tick networking pressure for multiplayer servers sending many small updates. tx_packets_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Outbound packets per second. rx_dropped_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- Inbound packets DROPPED per second. Sustained drops mean the server can't keep up with incoming traffic — a direct network cause of stalls/rubber-banding. tx_dropped_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Outbound packets dropped per second. rx_errors_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- Inbound packet errors per second (malformed/failed frames). Elevated errors point at a link or driver problem rather than application load. tx_errors_per_sec: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Outbound packet errors per second. required: - rx_bytes_per_sec - tx_bytes_per_sec description: >- Network I/O metrics (bytes, packets, and — for freeze diagnosis — dropped/error rates). load: type: object properties: average_1m: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- 1-minute load average over time. Values above the CPU count indicate the machine is overloaded. average_5m: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- 5-minute load average. Sustained load above the CPU count (more than a brief 1m spike) indicates a persistent overload likely to cause freezing. average_15m: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: >- 15-minute load average, for spotting slow-building saturation trends. required: - average_1m description: System load average metrics over 1/5/15-minute windows. connections: type: object properties: tcp: type: array items: type: object properties: t: type: number description: >- Unix timestamp (seconds since epoch) for this data point. v: type: number description: >- Metric value at this timestamp. Units depend on the metric: percent for CPU, megabytes for memory, bytes/sec for network, count for connections. required: - t - v description: A single time-series data point (timestamp + value). description: Number of active TCP connections over time. required: - tcp description: Network connection metrics. required: - instance_id - machine_id - region - compute_size - vcpus - lifecycle - period - cpu - memory - network - load - connections description: >- Server resource metrics including CPU, memory, network, load, and connections over a configurable time window. '404': description: Server not found or no machine assigned. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message describing what went wrong. detail: type: string description: >- Additional error context. May contain the same text as error or more specific technical details. status: type: number description: HTTP status code (matches the response status code). required: - error - status description: >- Standard error response returned by all API endpoints on failure. components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: api-key ````