Build with the tracker

Your first request

Start with a standalone calculation. This example asks how many flames are expected to improve an advantaged level-200 armor item from score 80 to 140.

curl --fail-with-body --silent --show-error \
  -H 'X-API-Client: my-guild-overlay' \
  'https://gms-upgrade-tracker.vercel.app/api/calc/flame?itemLevel=200&current=80&target=140'

Expected output: a JSON object with currentScore: 80, targetScore: 140, and a positive expectedFlames. Run it to see the current engine result.

Making requests

Players must publish or save their build online before lookup routes can read it. Data saved only in a browser is unavailable to the API. A lookup reads the tracker's stored build; it does not fetch a fresh equipment snapshot from Nexon.

Build an integration

A character card or guild overlay

Start with the compact summary. Preserve an unavailable score as null and show its reason while keeping the gear visible.

async function loadBuild(ign, region = 'na') {
  const url = new URL(
    '/api/build/' + encodeURIComponent(ign) + '/summary',
    'https://gms-upgrade-tracker.vercel.app',
  );
  url.searchParams.set('region', region);
  const response = await fetch(url, {
    headers: { 'X-API-Client': 'my-guild-overlay' },
    credentials: 'omit',
    signal: AbortSignal.timeout(15000),
  });
  const data = await response.json().catch(() => null);
  if (!response.ok) throw new Error(data?.error ?? ('HTTP ' + response.status));
  if (!data) throw new Error('Expected a JSON response');
  return {
    name: data.buildId,
    score: data.powerScore?.totalScore ?? null,
    unavailableReason: data.powerScoreUnavailableReason,
    gear: [...data.gear.wse, ...data.gear.armor, ...data.gear.accessories],
  };
}
// Replace with an IGN that has a published tracker build.
loadBuild('BobaSlayer', 'na').then(console.log).catch(console.error);

Want these features in a server without building your own integration? See the Discord bot guide.

Understanding results

• Expected cost is an average. Random upgrades can cost more or less. Cube percentile modes describe a distribution; a probability target is not a realized item. Never apply an expected roll to someone's saved gear.
• Percentages and fractions differ. expectedDamageGainPercent is already a percentage. Star Force plan success and boom are fractions. bossPDR=3.8 means 380% defense. Read the power-score reference for the special IED input convention.
• Keep useful partial results. A 200 response can include costAvailable=false, statGainAvailable=false, a null score, or input issues. Display the reason next to the withheld value, and preserve independent results.
• Keep estimate labels. Show estimated, estimateProvenance, calculationStatus, calculationProvenance, and assumptions when supplied. Null HEXA completion means unknown, not 0% complete.
• Compare equivalent inputs. These routes use the site's shared calculation engines, but different routes can use different boss-defense defaults and saved-build context. Matching mechanics alone does not make differently configured scores comparable.

Errors & retries

Validation and application errors usually return { "error": "message" }. Hosting or network failures can return plain text or HTML. Check the HTTP status before using a result and tolerate a non-JSON error body, as the quickstart does.

Use a request timeout. On a failed refresh, retain previously loaded data with a visible stale/error label. Avoid replacing a useful score or recommendation list with zeros.

Caching & responsible usage

Free to call does not mean unlimited capacity. We do not publish a fixed per-app quota or offer a dedicated capacity guarantee. Hosting and storage are paid by the project; efficient integrations help keep the API available.

• Follow the actual response's Cache-Control directives. Deployment and error paths can differ; do not assume every response is cacheable. Keep no-store responses out of persistent caches.
• Reuse cacheable results for identical parameters and combine simultaneous identical requests. Request only the endpoints and result counts your UI needs.
• As a starting integration policy, refresh visible standings about every five minutes and recommendations on user request. These are client design suggestions, not server-enforced limits. Pause background polling when the view is hidden.
• Do not add random cache-busting parameters. Reserve fresh=1 on the shared-build endpoint for deliberate reloads.

Tell us what you’re building

Optionally send X-API-Client: my-guild-overlay so we can see which integrations use the API. Choose a public app name: 2–40 letters, digits, or hyphens, starting with a letter. Names are normalized to lowercase. Invalid labels are ignored without rejecting the request.

Use one stable label for the app. Do not include tokens, email addresses, character names, Discord IDs, or other personal identifiers. Labels are self-declared; they are not API keys or verified identities.

When enabled, API telemetry records every documented GET request that reaches the server handler, without sampling. It retains daily aggregate endpoint counts, status groups, handler timing, coarse request-source hints, and optional app labels for 30 days. Cached responses that skip the handler, preflights, and other methods are excluded. Delivery is best-effort, so these counts are not an exactly-once billing record.

This API usage telemetry does not record IP addresses, raw URLs, user agents, credentials, or request/response bodies. This describes the API counter, not every hosting log or analytics system. See the privacy policy for the service policy. The header is optional and does not change API output.

Builds reference

Inputs are query parameters unless shown in the path. Response outlines below name fields and variants; they are not literal JSON examples or exhaustive nested schemas.

{ id, selectedClass, serverType, nexonRegion, characterStats, gear, characterLevel?, arcanePower?, sacredPower?, hexaProgress?, hexaAssumptionMode?, ozRingState?, autoRepairs? }

{ buildId, class, serverType, nexonRegion, effectivePrimaryStat, characterStats, powerScore, powerScoreUnavailableReason, hexaAssumptionMode, gear: { wse, armor, accessories } }

{ buildId, class, nexonRegion, assumptions, powerScore: { totalScore, bossPDRMultiplier, tier, breakdownAvailable: false }, recommendations, validationIssues, recommendationInputIssues, computeTimeMs }

{ buildId, nexonRegion, overall, class }

{ buildId, nexonRegion, selectedClass, hexaAssumptionMode, estimated: true, estimateProvenance, hexaScore, gearOnlyScore, scoreGap, completionPercent, fragmentProgressPercent, solErdaProgressPercent, breakdown }

Calculators reference

Inputs are query parameters unless shown in the path. Response outlines below name fields and variants; they are not literal JSON examples or exhaustive nested schemas.

{ costAvailable, costEngine: ordinary | superior | zero-paired | zero-paired-fixed, expectedCost, expectedBooms, expectedRecoveryResources: { replacementWeaponPairs, essence, luckyScroll: { applicationProbability, expectedRawScrolls, expectedOwnedScrollsConsumed, expectedPurchasedScrolls, ownedCoveragePercent } }, statGainAvailable, statGain, transposition: { inheritedResidual, sourceStars, destinationBaselineStars, includedInStatGain }, pairedStatGain: { alpha, beta }, aggregateFdAvailable, plan }

tierup: { mode, cubeType, currentTier, targetTier, costMode, countMeaning, steps: [{ from, to, expectedCubes }], totalCubes }
wse / glove: { mode, cubeType, costMode, countMeaning, combos: [{ id, label, expectedCubes, ... }], ... }
armor / hat: { mode, cubeType, costMode, countMeaning, targets: [{ id, label, expectedCubes, ... }], ... }

{ itemLevel, currentScore, targetScore, advantaged, flameType, flameLabel, expectedFlames }

{ totalScore, tier, bossPDRMultiplier, breakdownAvailable, breakdown, marginalValues, hexaAssumption, assumptions }

Leaderboard reference

Inputs are query parameters unless shown in the path. Response outlines below name fields and variants; they are not literal JSON examples or exhaustive nested schemas.

{ entries: [{ rank, name, displayName, selectedClass, nexonRegion, sharePath, score }], serverType, region }

Compatibility & help

The API currently uses unversioned paths. Calculation corrections can change numeric results, and optional fields can be added. Read the fields your app needs, tolerate additional fields, and handle missing or null values explicitly. There is no public SDK, webhook subscription, or bulk-export endpoint documented here.

For a failed lookup, open the published character on the site and check the same region first. For a calculator discrepancy, compare the exact item context, event settings, and returned assumptions.

Use the site’s Feedback button to report an integration issue. Include the endpoint, non-sensitive parameters, HTTP status, returned error, and time of failure. Never send credentials or an unpublished profile.

Documentation expanded September 14, 2026: complete input tables, integration examples, response caveats, and optional API usage labels. Related: Discord commands · Interactive calculators.