Reports API Queries

This section documents the GraphQL queries available in the Reports API for retrieving platform statistics and metrics.

onlinePlayers

Returns the number of users currently online on the platform.

Request

query {
  onlinePlayers
}

Authentication

• No authentication required

Response

Returns a single number representing the count of online players.

{
  "data": {
    "onlinePlayers": 127
  }
}

Response Details

Field	Type	Description
onlinePlayers	Int	The number of users currently connected to the platform

Cache Behavior

• The result is cached for 60 seconds
• Each new request within the cache window returns the same count
• After the cache expires, the count is recalculated from Redis data

Use Cases

1. Dashboard Statistics: Display real-time user activity on admin dashboards
2. Public Information: Show how many users are online on public areas of the site
3. Platform Health Monitoring: Track user engagement over time by polling this endpoint

Implementation Notes

Behind the scenes, this query:

1. Checks if there's a cached count available
2. If not, it queries Redis for all keys matching the WebSocket user pattern
3. Counts the number of matching keys
4. Caches the result for 60 seconds

Error Handling

This query typically doesn't produce errors since it's retrieving aggregate data. However, in case of Redis connectivity issues, standard GraphQL errors may be returned.

Future Queries

Additional report queries planned for future implementation:

• activeUsers: Count of users active within specific time periods (daily, weekly, monthly)
• regionalDistribution: Breakdown of users by geographic region
• platformBreakdown: Distribution of users across different devices/platforms