Nexardo

Satisfactory Field guide

Read Satisfactory Dedicated Server State Through HTTPS API: Endpoints and Metrics

Querying Satisfactory dedicated server metrics via HTTPS API: unauthenticated HealthCheck, PasswordLogin Bearer auth, QueryServerState payloads, and UDP game port validation.

EugenePublishedUpdatedReading time4 min
Read Satisfactory Dedicated Server State Through HTTPS API: Endpoints and Metrics

The Satisfactory Dedicated Server (starting with the version 1.0 release branch) incorporates a native HTTP management interface: the Satisfactory Dedicated Server HTTPS API v1. This feature allows systems engineers and dashboard developers to abandon fragile, custom log-parsing scripts and query ground-truth factory operational metrics directly from the Unreal Engine runtime: active player counts, server tickrate, loaded save session name, autosave status, and current technology milestone tiers.

However, when integrating this API into automated monitoring infrastructures (such as Prometheus, Grafana, Zabbix, or custom alerts), operators frequently run into TLS handshake failures, token permission discrepancies, or misleading uptime reports.

Architecture, Networking Ports, and Handling Self-Signed TLS Certificates#

The Satisfactory Dedicated Server API communicates over HTTPS and listens by default on the server's primary network port (typically 7777 TCP/UDP). Unlike typical RESTful endpoints mapped across distinct resource paths, Satisfactory's API implements an RPC-style design: all requests are submitted as POST requests to a unified base path (/api/v1), with the specific procedure declared via the "function" parameter in the JSON payload.

By default, the server daemon generates a self-signed TLS certificate upon its initial start. Command-line clients such as curl must either bypass verification using the -k (--insecure) flag or install the server's exported public TLS certificate into the operating system's trust store.

The fastest way to verify daemon responsiveness is executing an unauthenticated HealthCheck probe:

bash
curl -k -s -X POST https://127.0.0.1:7777/api/v1 \
  -H "Content-Type: application/json" \
  -d '{"function": "HealthCheck", "data": {"clientCustomData": "monitoring-probe"}}'

The server returns a heartbeat confirmation object:

json
{
  "data": {
    "health": "healthy",
    "serverCustomData": ""
  }
}

A healthy status verifies that the embedded web service within the Satisfactory executable is active and capable of processing incoming requests.

Administrator Authentication and Bearer Token Generation#

While HealthCheck validates process vitality, it returns zero insight into gameplay states. Accessing operational diagnostics (including QueryServerState, SaveGame, and server shutdown routines) requires an authenticated Bearer token.

To obtain an authentication token, execute the PasswordLogin procedure with the server's administrator password configured during initial setup:

bash
TOKEN=$(curl -k -s -X POST https://127.0.0.1:7777/api/v1 \
  -H "Content-Type: application/json" \
  -d '{"function": "PasswordLogin", "data": {"minimumPrivilegeLevel": "Administrator", "password": "SuperSecretServerPassword"}}' \
  | jq -r '.data.authenticationToken')
echo "Token length: ${#TOKEN}"

The resulting token is a cryptographically signed credential string. Because Administrator tokens carry authorization to trigger server shutdowns and download raw save archives, tokens must never be hardcoded into public repositories or logged in plain text.

Querying Real-Time State Metrics: QueryServerState Function#

With a valid token supplied in the Authorization: Bearer <TOKEN> header, monitoring daemons can periodically query runtime metrics via QueryServerState:

bash
curl -k -s -X POST https://127.0.0.1:7777/api/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"function": "QueryServerState"}' | jq '.data.serverGameState'

The server responds with a granular status payload detailing active factory state:

json
{
  "activeSessionName": "Apex-Factory-1.0",
  "numConnectedPlayers": 4,
  "playerLimit": 8,
  "techTier": 9,
  "isGameRunning": true,
  "totalGameDuration": 412800,
  "isGamePaused": false,
  "averageTickRate": 30.0,
  "autoLoadSessionName": "Apex-Factory-1.0"
}

Key operational fields for health monitoring:

  • isGameRunning — boolean indicator confirming the world save has completed loading into memory and the game loop is active;
  • averageTickRate — actual server simulation tick rate (baseline target: 30.0). Sustained drops below 20 indicate CPU starvation from heavy factory logistics;
  • numConnectedPlayers — active player count currently connected to the server session;
  • isGamePaused — pause state flag (relevant when automatic pausing on zero connected players is active).

Distinguishing API Health from UDP Game Joinability#

A frequent diagnostic oversight is treating an HTTP 200 return from /api/v1 as definitive proof that the game server is healthy and joinable.

The Satisfactory management API operates over TCP, whereas live client game sessions, entity synchronization, and voice traffic flow over UDP. When firewall configurations permit TCP traffic on port 7777 while dropping UDP packets, monitoring systems falsely report the host as operational while human players experience immediate connection timeouts.

A robust monitoring check must concurrently probe the UDP socket state:

bash
nc -z -v -u 127.0.0.1 7777

Only when an unauthenticated or authenticated API call returns isGameRunning: true AND the corresponding UDP gameplay socket responds cleanly can the host be confirmed fully operational for client connections.

To support massive megafactory constructions with uncompromised tick rates and modern API integration, host your world on an optimized gaming server backed by high-clock CPU cores.

References#