115 online 3 members  + Join RP Base  +
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
fivem-server-api
Package for getting information about a FiveM server via its API endpoints.
Installation
npm i fivem-server-api

CLI
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=15000

Usage
// 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:30120
IP only, 205.178.183.132
Domain:PORT, myserver.com:30120
CFX.re short URL, cfx.re/join/my59jq
CFX.re full URL, https://cfx.re/join/my59jq
CFX.re code only, my59jq
Basic 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 milliseconds
retries, number, 0, Number of retry attempts on failure
retryDelay, number, 1000, Delay between retries in milliseconds
cacheTtl, number, 5000, Cache duration for info.json in ms. Set 0 to disable
debug, boolean \, (msg: string) => void, false, Enable logging. Pass true for console.log, or a custom logger function
minInterval, 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:PORT
clearCache(), void, Clear cached info.json to force re-fetch
playerCount, 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 status
getServer(), Promise, Yes, Full server info from info.json
getServerName(), Promise, Yes, Server name (color codes stripped)
getServerDesc(), Promise, Yes, Server description
getPlayers(), Promise, Yes, Number of players online
getPlayersAll(), Promise, Yes, All players with name, ping, identifiers
getPlayer(query), Promise, Yes, Search by id (number), name substring, or identifier
getMaxPlayers(), Promise, Yes, Max player slots
getResources(), Promise, Yes, Resource names
getTags(), Promise, Yes, Server tags (comma-separated)
getOnesync(), Promise, Yes, OneSync enabled
getLocale(), Promise, Yes, Server locale (e.g. id-ID)
getGamename(), Promise, Yes, Game name (e.g. gta5)
getSteamTicket(), Promise, Yes, Steam ticket required
getGameBuild(), Promise, Yes, Enforced game build
getEnhancedHostSupport(), Promise, Yes, Enhanced host support
getLicenseKeyToken(), Promise, Yes, License key token
getScriptHookAllowed(), Promise, Yes, ScriptHook allowed
getEndpoint(), Promise, Yes, Dynamic server endpoint
getIcon(), Promise, Yes, Server icon (base64 data URI)
getUpvotePower(), Promise, Yes, Server upvote power
getBurstPower(), Promise, Yes, Server burst power (boost)
getClients(), Promise, Yes, Player count via lightweight dynamic.json. Falls back to players.json
getHostname(), Promise, Yes, Raw hostname from dynamic.json. Falls back to sv_projectName
getGametype(), 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.json
getOwnerName(), Promise, Yes, Owner display name
getOwnerProfile(), Promise, Yes, Owner forum profile URL
getOwnerAvatar(), Promise, Yes, Owner avatar URL
Player 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 servers

Server 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 {

…