Session Management

session management is at the core of the gameye session api these endpoints allow you to create new game sessions, list active sessions, and stop sessions when they're no longer needed creating a session to start a new game session, you'll need to make a post request to the /session endpoint endpoint post /session request body the request requires a json body with the following fields true 165,165,165,166left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type example request { "location" "eu central 1", "image" "my game server", "env" { "max players" "16", "map rotation" "de dust2,de inferno,de nuke" }, "args" \[ " tickrate=128", " competitive=true" ], "labels" { "game mode" "competitive", "tournament id" "spring cup 2023" }, "restart" false } success response on success, you'll receive a 201 created response with details about the new session { "id" "c5c7c507 f5de 443e b772 af4b444cfc21", "host" "203 0 113 42", "ports" \[ { "type" "tcp", "container" 80, "host" 25159 }, { "type" "tcp", "container" 80, "host" 25160 } ] } note host ports are now allocated from the dedicated range of 20000 30000 to prevent conflicts with the linux kernel's ephemeral port range, improving server startup reliability error responses true 330,331left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type error response example { "statuscode" 404, "code" "resource not found", "message" "unable to start session ", "details" "please make sure the correct image is specified ", "identifier" "3bc545b7 4750 47e6 a918 c93debc58663", "path" "/session", "timestamp" "2023 04 01t12 00 00z" } 🔍 tip always include the identifier when contacting support about errors this helps us quickly trace the exact issue in our systems listing sessions to get a list of your active sessions, use the get request to the /session endpoint endpoint get /session query parameters true 165,165,165,166left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type filtering examples include filter ( filter ) get /session?filter\[location]=eu central 1\&filter\[tag]=latest returns sessions matching all specified criteria exclude filter ( filternot ) get /session?filternot\[status]=exited\&filternot\[tag]=beta excludes sessions that match the specified criteria historical sessions ( all ) get /session?all=true include non running sessions (like exited ones) in the results you can combine these filters for precise querying get /session?all=true\&filter\[location]=eu central 1\&filternot\[status]=dead this would return all sessions (including exited ones) in eu central 1, excluding dead sessions example response { "sessions" \[ { "id" "c595bc6f 8522 4a62 95cd 8742136643ea", "image" "my game server", "tag" "v1 2 3", "location" "eu central 1", "host" "203 0 113 42", "created" 1648472895000, "port" { "80/tcp" 25160 }, "status" "running", "labels" { "env" "{\\"gameye session id\\" \\"c595bc6f 8522 4a62 95cd 8742136643ea\\",\\"gameye host\\" \\"a b c d\\"}", "tags" "{\\"my example tag\\" \\"1\\",\\"another example tag\\" \\"3\\"}" } } ] } stopping a session when a game session is over, you can stop it using the delete request endpoint delete /session/{id} path parameters true 165,165,165,166left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type success response on success, you'll receive a 204 no content response, indicating the session was successfully terminated error responses true 330,331left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type session lifecycle a typical session lifecycle looks like this creation you create a session with post /session running the session runs until you stop it or it crashes termination you stop the session with delete /session/{id} cleanup you can download artifacts if needed session status values when listing sessions, the status field will be one of true 330,331left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type best practices let the system generate session ids when possible use labels to organize and filter your sessions always stop sessions when they're no longer needed to free up resources check session status before performing operations on them use the combined filtering capabilities to efficiently manage many sessions