Server Statistics

Operations return statistics for servers in the selected project. The public current-online counter is independent of the history-chart switch, but requires site.statistics.online: true. See publication switches, characters and accounts; absent settings mean publication is disabled.

Current online

QuerydocumentId: serversOnlineauth: public

`serversOnline`

Published online for one, several or all servers in the current project through the shared GraphQL endpoint.

Server selection

Omit gameServerIds or pass null for all project servers.
gameServerIds: [1]: one server.
gameServerIds: [1, 2]: selected servers, from 1 to 100 distinct IDs.
Use unique IDs of servers in the selected project; an empty list is invalid.

Result

Response type: [ServerOnline!]. The outer list is nullable: disabling site.statistics.online returns null for the entire field. With publication enabled, a project without servers returns an empty list.

Field	Type	Description
`gameServerId`	`Int!`	Game server.
`state`	`ServerOnlineState!`	`FRESH`, `STALE`, `MISSING` or `UNAVAILABLE`.
`current`	`UnsignedInt`	Published online count with the configured offset and multiplier already applied.
`peak`	`UnsignedInt`	Highest published count among retained observations.
`observedAt`	`String`	Measurement time in UTC, RFC 3339.
`staleAt`	`String`	Time after which the measurement becomes stale.
`loginAvailable`	`Boolean`	Login server availability check.
`gameAvailable`	`Boolean`	Game server availability check.

UnsignedInt is a JSON number from 0 to 4,294,967,295, not a string.

0 is a measured zero. MISSING means no observation; UNAVAILABLE means the data is temporarily unavailable. Both return null counts and timestamps. STALE preserves the last measured value and time. A positive count is not evidence that a server is reachable.

Availability checks return null when no current result exists or the check is not configured. Use staleAt when displaying a cached response. Do not apply the multiplier again on the website.

Sum the required response rows for a combined count. If any measurement is missing, do not label the subtotal as the full online population. If any observation is stale, mark the combined count as stale too.

Request and response

Request

documentId: serversOnline
{
  "documentId": "serversOnline",
  "variables": {
    "gameServerIds": [
      1,
      2
    ]
  }
}

Response

200 OK
{
  "data": {
    "serversOnline": [
      {
        "gameServerId": 1,
        "state": "FRESH",
        "current": 1250,
        "peak": 1800,
        "observedAt": "2026-09-08T13:30:00.000000Z",
        "staleAt": "2026-09-08T13:40:00.000000Z",
        "loginAvailable": true,
        "gameAvailable": true
      },
      {
        "gameServerId": 2,
        "state": "MISSING",
        "current": null,
        "peak": null,
        "observedAt": null,
        "staleAt": null,
        "loginAvailable": null,
        "gameAvailable": null
      }
    ]
  }
}

Online history

QuerydocumentId: serverOnlineHistoryauth: public

`serverOnlineHistory`

Published online history and permitted population series. Each point is the average of actual observations in a time bucket, not an individual sample. Unobserved buckets are not filled with zeros.

Project switches apply in addition to server series settings: disabling site.statistics.online hides points[].online, and disabling site.statistics.characters hides points[].characters. Hidden values are null. The example below assumes publication is enabled for both metrics.

Input

Field	Type	Description
`gameServerId`	`Int!`	Accessible game server ID.
`range`	`OnlineReportRange!`	Period. Defaults to `WEEK`.

Range	Duration	Chart bucket
`DAY`	Previous 24 hours	5 minutes
`WEEK`	Previous 7 days	15 minutes
`MONTH`	Previous 30 days	1 hour
`QUARTER`	Previous 90 days	3 hours

Response

ServerOnlineHistory!

Field	Type	Description
`meta`	`OnlineReportMetadata!`	Measurement state and update timestamps.
`period`	`OnlineReportPeriod`	UTC boundaries `from`, `until` with an inclusive start and exclusive end.
`bucketSeconds`	`Int`	Bucket duration in seconds.
`points`	`[OnlineHistoryBucket!]!`	At most 721 observed buckets in chronological order.
`points[].timestamp`	`String!`	RFC3339 UTC bucket start. The first bucket can start before `period.from`.
`points[].samples`	`UnsignedInt!`	Number of observations within the requested period in that bucket.
`points[].online`	`Float`	Average published online; `null` when hidden.
`points[].characters`	`Float`	Average character count; `null` when hidden.
`points[].clans`	`Float`	Average clan count; `null` when hidden or unsupported.

Without observations or permitted series, points is empty. A measured zero remains 0; unobserved periods remain chart gaps.

Data State

The meta.state field contains FRESH, STALE, MISSING or UNAVAILABLE. Freshness describes the latest observation, not the age of a record or historical point.

generatedAt is the response generation time, observedAt the last observation, and staleAt the time after which it is stale. All timestamps use RFC3339 UTC. With MISSING the observation dates are null. With UNAVAILABLE dates, report periods and scalar values are null, and collections are empty.

An unavailable section or invalid input returns a GraphQL error without data. Do not replace an error with a MISSING or zero report.

Request and Response

Request

documentId: serverOnlineHistory
{
  "documentId": "serverOnlineHistory",
  "variables": {
    "gameServerId": 97010,
    "range": "DAY"
  }
}

Response

200 OK
{
  "data": {
    "serverOnlineHistory": {
      "meta": {
        "state": "STALE",
        "generatedAt": "2026-09-08T17:29:57.251Z",
        "observedAt": "2026-09-08T17:19:26.799Z",
        "staleAt": "2026-09-08T17:29:26.799Z"
      },
      "period": {
        "from": "2026-09-07T17:29:57.000000Z",
        "until": "2026-09-08T17:29:57.000000Z"
      },
      "bucketSeconds": 300,
      "points": [
        {
          "timestamp": "2026-09-08T15:00:00Z",
          "samples": 6,
          "online": 6.333333333333333,
          "characters": 12,
          "clans": 4
        },
        {
          "timestamp": "2026-09-08T17:15:00Z",
          "samples": 6,
          "online": 6.333333333333333,
          "characters": 12,
          "clans": 4
        }
      ]
    }
  }
}

Ranking Timeline

QuerydocumentId: serverTimelineauth: public

`serverTimeline`

Description

Leader changes and movement in published rankings with cursor pagination. This is not an online-change log. If a cursor is invalid or stale, start from the first page.

Input

Field	Type	Required	Description
`gameServerId`	`Int`	✓	Game server ID.
`first`	`Int`	no	Page size from 1 to 50. Defaults to 20.
`after`	`String`	no	Cursor from the previous page's `pageInfo.endCursor`.

Result

Response type - TimelineEventConnection!. Events are returned in nodes, with pagination state in pageInfo.

Errors

SERVER_NOT_FOUND - server was not found or is unavailable.
VALIDATION - required parameters are invalid.

Exchange example

Request

documentId: serverTimeline
{
  "documentId": "serverTimeline",
  "variables": {
    "gameServerId": 1,
    "first": 20,
    "after": null
  }
}

Response

200 OK
{
  "data": {
    "serverTimeline": {
      "nodes": [
        {
          "date": "2026-07-17 18:30:00",
          "event": "new_leader",
          "data": {
            "type": "top_pvp",
            "name": "Asterios",
            "value": 18420
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJrZXkiOiJjOGQwMTc4MTBlMzA2MzQyN2VmMzg1ODhjYjVkN2EzNzgyNDQzMTE1OWJhY2YwMmI0MDRiMmEyY2Q0MmEyY2Y3In0"
      }
    }
  }
}

Server operation reference

Online records

QuerydocumentId: serverRecordsauth: public

`serverRecords`

Maximum published online with the first observation time when equal peaks occurred. Records use retained observations; removed history does not participate.

Input

Field	Type	Description
`gameServerId`	`Int!`	Accessible game server ID.

Response

ServerRecords!

Field	Type	Description
`meta`	`OnlineReportMetadata!`	Measurement state and update timestamps.
`allTime`	`OnlineRecord`	Maximum over retained history.
`today`	`OnlineRecord`	Since the start of the current UTC day.
`week`	`OnlineRecord`	Over the previous 7 days.
`month`	`OnlineRecord`	Since the start of the current UTC calendar month.
`value`	`UnsignedInt!`	Observed maximum, including `0`.
`observedAt`	`String!`	Record observation time in RFC3339 UTC.

Each record is null when its period has no observations. No dates or zero records are invented. Selecting a chart range does not change these four record periods.

Data State

The meta.state field contains FRESH, STALE, MISSING or UNAVAILABLE. Freshness describes the latest observation, not the age of a record or historical point.

generatedAt is the response generation time, observedAt the last observation, and staleAt the time after which it is stale. All timestamps use RFC3339 UTC. With MISSING the observation dates and all four records are null. With UNAVAILABLE all dates in meta and all four records are null.

An unavailable section or invalid input returns a GraphQL error without data. Do not replace an error with a MISSING or zero report.

Request and Response

Request

documentId: serverRecords
{
  "documentId": "serverRecords",
  "variables": {
    "gameServerId": 97010
  }
}

Response

200 OK
{
  "data": {
    "serverRecords": {
      "meta": {
        "state": "STALE",
        "generatedAt": "2026-09-08T17:29:51.696Z",
        "observedAt": "2026-09-08T17:19:26.799Z",
        "staleAt": "2026-09-08T17:29:26.799Z"
      },
      "allTime": {
        "value": 9,
        "observedAt": "2026-09-08T15:03:26.016Z"
      },
      "today": {
        "value": 9,
        "observedAt": "2026-09-08T15:03:26.016Z"
      },
      "week": {
        "value": 9,
        "observedAt": "2026-09-08T15:03:26.016Z"
      },
      "month": {
        "value": 9,
        "observedAt": "2026-09-08T15:03:26.016Z"
      }
    }
  }
}

Activity heatmap

QuerydocumentId: serverActivityHeatmapauth: public

`serverActivityHeatmap`

Average published online by UTC weekday and hour over the selected period. Only observed cells are returned.

Input

Field	Type	Description
`gameServerId`	`Int!`	Accessible game server ID.
`range`	`OnlineReportRange!`	Period. Defaults to `MONTH`.

Allowed ranges: DAY (24 hours), WEEK (7 days), MONTH (30 days), QUARTER (90 days).

Response

ServerActivityHeatmap!

Field	Type	Description
`meta`	`OnlineReportMetadata!`	Measurement state and update timestamps.
`period`	`OnlineReportPeriod`	UTC boundaries `from`, `until` with an inclusive start and exclusive end.
`cells`	`[OnlineActivityCell!]!`	At most 168 observed cells.
`cells[].weekday`	`Int!`	1 (Monday) through 7 (Sunday).
`cells[].hour`	`Int!`	UTC hour, 0 through 23.
`cells[].samples`	`UnsignedInt!`	Observation count.
`cells[].average`	`Float!`	Mean of the cell observations, including measured zeros.

An absent cell means no observations, not zero online.

Data State

The meta.state field contains FRESH, STALE, MISSING or UNAVAILABLE. Freshness describes the latest observation, not the age of a record or historical point.

An unavailable section or invalid input returns a GraphQL error without data. Do not replace an error with a MISSING or zero report.

Request and Response

Request

documentId: serverActivityHeatmap
{
  "documentId": "serverActivityHeatmap",
  "variables": {
    "gameServerId": 97010,
    "range": "DAY"
  }
}

Response

200 OK
{
  "data": {
    "serverActivityHeatmap": {
      "meta": {
        "state": "STALE",
        "generatedAt": "2026-09-08T17:29:57.420Z",
        "observedAt": "2026-09-08T17:19:26.799Z",
        "staleAt": "2026-09-08T17:29:26.799Z"
      },
      "period": {
        "from": "2026-09-07T17:29:57.000000Z",
        "until": "2026-09-08T17:29:57.000000Z"
      },
      "cells": [
        {
          "weekday": 2,
          "hour": 15,
          "samples": 6,
          "average": 6.333333333333333
        },
        {
          "weekday": 2,
          "hour": 17,
          "samples": 6,
          "average": 6.333333333333333
        }
      ]
    }
  }
}

Class Distribution

QuerydocumentId: rankingClassDistributionauth: public

`rankingClassDistribution`

Counts each character once across the currently published character rankings, within their configured top limits. This is not the total world population. If observations disagree, the freshest class observation is selected; an unknown class is not replaced with an older known value.

Requires the class-distribution section and site.statistics.characters publication. Character leaderboard tables and rising-player results remain independently configurable.

The only input is gameServerId: Int!, a positive server ID belonging to the current project. No names or account information are returned.

Result field	Meaning
`state`	`FRESH`, `STALE`, `PARTIAL`, `MISSING`, `SOURCE_ERROR` or `UNAVAILABLE`.
`generatedAt`, `observedAt`	Report timestamps in UTC; null for `UNAVAILABLE`.
`totalCharacters`	Distinct characters in the available published tops.
`unknownCharacters`	Characters whose freshest observation has no class code.
`classes`	`code` and integer `count`, ordered by count descending and code ascending. Code `"0"` is valid.
`sources`	Each selected ranking's `type`, `state`, `snapshotId`, `capturedAt` and `staleAt`. Missing-source metadata is null.

sum(classes.count) + unknownCharacters = totalCharacters. Percentages use this total, including unknown classes. The client resolves class codes using its game dictionary; these are not race codes.

PARTIAL means some selected rankings are missing or failed; the counts cover the remaining observations. STALE keeps available but delayed observations. Successful empty observations return FRESH or STALE with zero counts. MISSING and SOURCE_ERROR have zero counted characters but do not prove an empty game world. UNAVAILABLE returns null counts, empty lists and null timestamps.

Request

documentId: rankingClassDistribution
{
  "documentId": "rankingClassDistribution",
  "variables": {
    "gameServerId": 1
  }
}

Response

200 OK
{
  "data": {
    "rankingClassDistribution": {
      "state": "PARTIAL",
      "generatedAt": "2026-09-09T10:00:00.000Z",
      "observedAt": "2026-09-09T10:00:00.000Z",
      "totalCharacters": 6,
      "unknownCharacters": 1,
      "classes": [
        {
          "code": "88",
          "count": 3
        },
        {
          "code": "94",
          "count": 2
        }
      ],
      "sources": [
        {
          "type": "top_exp",
          "state": "FRESH",
          "snapshotId": "01a07fab-8130-7000-8000-000000000001",
          "capturedAt": "2026-09-09T09:59:00.000Z",
          "staleAt": "2026-09-09T10:59:00.000Z"
        },
        {
          "type": "top_hero",
          "state": "MISSING",
          "snapshotId": null,
          "capturedAt": null,
          "staleAt": null
        }
      ]
    }
  }
}

Current online​

serversOnline​

Server selection​

Result​

Request and response​

Online history​

serverOnlineHistory​

Input​

Response​

Data State​

Request and Response​

Ranking Timeline​

serverTimeline​

Description​

Input​

Result​

Errors​

Exchange example​

Related types​

Online records​

serverRecords​

Input​

Response​

Data State​

Request and Response​

Activity heatmap​

serverActivityHeatmap​

Input​

Response​

Data State​

Request and Response​

Class Distribution​

rankingClassDistribution​

Current online

`serversOnline`

Server selection

Result

Request and response

Online history

`serverOnlineHistory`

Input

Response

Data State

Request and Response

Ranking Timeline

`serverTimeline`

Description

Input

Result

Errors

Exchange example

Related types

Online records

`serverRecords`

Input

Response

Data State

Request and Response

Activity heatmap

`serverActivityHeatmap`

Input

Response

Data State

Request and Response

Class Distribution

`rankingClassDistribution`