FreeScript
fivem-server-api
by AvuxDemons · version 2026.06.20 · updated 3 days ago
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 39 KB
- Code check
- Clean
- Licence
- Apache-2.0
- Released
- Nov 2026
JavaScript API for getting information about FiveM Server
fivem-server-api
Package for getting information about a FiveM server via its API endpoints.
Installation
CLI
Usage
Accepted Input Formats
Format, Example
IP:PORT,
IP only,
Domain:PORT,
CFX.re short URL,
CFX.re full URL,
CFX.re code only,
Basic Example
Error Handling
All methods throw
Options
Option, Type, Default, Description
Method ListProperties & Control
Method, Returns, Description
Data Methods
Method, Returns, Throws, Description
Player Search
Watch (Polling)
Multi-Server
Server Search
Search the global FiveM server list from Cfx.re. By default returns 20 results — pass
```js
import {
…
Package for getting information about a FiveM server via its API endpoints.
Installation
npm i fivem-server-apiCLI
npx fivem-server-api cfx.re/join/my59jq
npx fivem-server-api 1.2.3.4:30120 --json
npx fivem-server-api cfx.re/join/code --timeout=15000Usage
// ESM
import FiveM, { FiveMError } from "fivem-server-api";
// CJS
const FiveM = require("fivem-server-api");Accepted Input Formats
Format, Example
IP:PORT,
205.178.183.132:30120IP only,
205.178.183.132Domain:PORT,
myserver.com:30120CFX.re short URL,
cfx.re/join/my59jqCFX.re full URL,
https://cfx.re/join/my59jqCFX.re code only,
my59jqBasic Example
import FiveM from "fivem-server-api";
const server = new FiveM("cfx.re/join/my59jq", { timeout: 10000 });
const online = await server.getServerStatus();
if (online) {
const info = await server.getServer();
console.log("Name:", await server.getServerName());
console.log("Players:", await server.getPlayers());
console.log("Resources:", (await server.getResources()).length);
}Error Handling
All methods throw
FiveMError on failure, except getServerStatus() which returns false when unreachable.
import FiveM, { FiveMError } from "fivem-server-api";
const server = new FiveM("1.2.3.4:30120");
try {
const players = await server.getPlayersAll();
console.log(`Online: ${players.length}`);
} catch (err) {
if (err instanceof FiveMError) {
console.error(`[${err.method}] ${err.message}`);
}
}FiveMError properties: name, message, method, url, status, cause.Options
Option, Type, Default, Description
timeout, number, 5000, Request timeout in millisecondsretries, number, 0, Number of retry attempts on failureretryDelay, number, 1000, Delay between retries in millisecondscacheTtl, number, 5000, Cache duration for info.json in ms. Set 0 to disabledebug, boolean \, (msg: string) => void, false, Enable logging. Pass true for console.log, or a custom logger functionminInterval, number, 0, Minimum delay between requests in ms (rate limiting)
const server = new FiveM("cfx.re/join/code", {
timeout: 10000,
retries: 2,
retryDelay: 1000,
cacheTtl: 0,
debug: (msg) => console.log("[DEBUG]", msg),
minInterval: 500,
});Method ListProperties & Control
Method, Returns, Description
ready(), Promise, Resolves when server IP is resolved (CFX.re). No-op for IP:PORTclearCache(), void, Clear cached info.json to force re-fetchplayerCount, number, Sync getter — cached count from last getPlayers()/getPlayersAll()/getServer()getIp(), string, Resolved server IP:PORT (sync)Data Methods
Method, Returns, Throws, Description
getServerStatus(), Promise, No, Server online statusgetServer(), Promise, Yes, Full server info from info.jsongetServerName(), Promise, Yes, Server name (color codes stripped)getServerDesc(), Promise, Yes, Server descriptiongetPlayers(), Promise, Yes, Number of players onlinegetPlayersAll(), Promise, Yes, All players with name, ping, identifiersgetPlayer(query), Promise, Yes, Search by id (number), name substring, or identifiergetMaxPlayers(), Promise, Yes, Max player slotsgetResources(), Promise, Yes, Resource namesgetTags(), Promise, Yes, Server tags (comma-separated)getOnesync(), Promise, Yes, OneSync enabledgetLocale(), Promise, Yes, Server locale (e.g. id-ID)getGamename(), Promise, Yes, Game name (e.g. gta5)getSteamTicket(), Promise, Yes, Steam ticket requiredgetGameBuild(), Promise, Yes, Enforced game buildgetEnhancedHostSupport(), Promise, Yes, Enhanced host supportgetLicenseKeyToken(), Promise, Yes, License key tokengetScriptHookAllowed(), Promise, Yes, ScriptHook allowedgetEndpoint(), Promise, Yes, Dynamic server endpointgetIcon(), Promise, Yes, Server icon (base64 data URI)getUpvotePower(), Promise, Yes, Server upvote powergetBurstPower(), Promise, Yes, Server burst power (boost)getClients(), Promise, Yes, Player count via lightweight dynamic.json. Falls back to players.jsongetHostname(), Promise, Yes, Raw hostname from dynamic.json. Falls back to sv_projectNamegetGametype(), Promise, Yes, Game type from dynamic.json (Roleplay, Freeroam, etc.)getMapname(), Promise, Yes, Map name from dynamic.json (San Andreas, etc.)getSvMaxclients(), Promise, Yes, Max clients from dynamic.json. Falls back to info.jsongetOwnerName(), Promise, Yes, Owner display namegetOwnerProfile(), Promise, Yes, Owner forum profile URLgetOwnerAvatar(), Promise, Yes, Owner avatar URLPlayer Search
// By ID (number — exact match)
const player = await server.getPlayer(42);
// By name (string — case-insensitive substring)
const player = await server.getPlayer("playername");
// By identifier (string starting with license:/steam:/discord: — exact match)
const player = await server.getPlayer("license:abc123def");Watch (Polling)
const handle = server.watch(5000, async (s) => {
const count = await s.getPlayers();
console.log(`Players: ${count} (cached: ${s.playerCount})`);
});
// Later: handle.stop();Multi-Server
const result = await FiveM.multi([
{ cfxre: "1.2.3.4:30120" },
{ cfxre: "cfx.re/join/code1" },
{ cfxre: "cfx.re/join/code2", options: { timeout: 10000 } },
]);
console.log("All servers:", result.servers.length);
const statuses = await result.getAllStatus();
// Map — IP → online/offline
const counts = await result.getAllPlayers();
// Map — IP → player count (-1 if failed)
const online = await result.getOnlineServers();
// Server[] — only online serversServer Search
Search the global FiveM server list from Cfx.re. By default returns 20 results — pass
0 for unlimited. Stops decoding early when enough matches are found.```js
import {
…