Skip to main content
This is an administrator-only endpoint. Requires admin authentication.

​
Overview

Allows administrators to run SELECT queries against the RaidHub database or explain query execution plans. Includes automatic cost analysis to prevent expensive queries from running.

​
Endpoint

POST /admin/query

​
Authentication

Requires admin JWT token obtained from /authorize/admin.

​
Request Body

​
query
string
required
The SQL query to execute. Must be a SELECT statement.
​
type
string
required
Type of query execution. One of:
  • SELECT: Execute the query and return results
  • EXPLAIN: Return the query execution plan without executing
​
ignoreCost
boolean
default:"false"
Skip cost analysis and execute the query regardless of estimated cost. Use with caution.

​
Response

The response structure varies based on the query type and cost:

​
SELECT Response (Low Cost)

​
type
string
required
SELECT
​
data
array
required
Array of result rows (limited to 50 rows). Each row is an object with column names as keys.

​
SELECT Response (High Cost)

Returned when estimated query cost exceeds 1,000,000 and ignoreCost is false:
​
type
string
required
HIGH COST
​
data
null
required
Always null for high cost queries
​
cost
number
required
Estimated query cost from PostgreSQL query planner
​
estimatedDuration
number
required
Estimated query duration in seconds

​
EXPLAIN Response

​
type
string
required
EXPLAIN
​
data
array
required
Array of query plan lines as strings

​
Example Requests

​
Execute a Query

{
  "query": "SELECT instance_id, date_completed FROM instance WHERE completed = true LIMIT 10",
  "type": "SELECT",
  "ignoreCost": false
}

​
Explain Query Execution

{
  "query": "SELECT COUNT(*) FROM player WHERE last_seen > NOW() - INTERVAL '7 days'",
  "type": "EXPLAIN"
}

​
Example Responses

​
Successful SELECT

{
  "minted": "2024-03-03T23:30:00.000Z",
  "success": true,
  "response": {
    "type": "SELECT",
    "data": [
      {
        "instance_id": "12345678901234567",
        "date_completed": "2024-03-01T15:30:00.000Z"
      },
      {
        "instance_id": "12345678901234568",
        "date_completed": "2024-03-01T16:45:00.000Z"
      }
    ]
  }
}

​
High Cost Warning

{
  "minted": "2024-03-03T23:30:00.000Z",
  "success": true,
  "response": {
    "type": "HIGH COST",
    "data": null,
    "cost": 2500000,
    "estimatedDuration": 25.0
  }
}

​
Explain Plan

{
  "minted": "2024-03-03T23:30:00.000Z",
  "success": true,
  "response": {
    "type": "EXPLAIN",
    "data": [
      "Aggregate  (cost=1234.56..1234.57 rows=1 width=8)",
      "  ->  Seq Scan on player  (cost=0.00..1200.00 rows=9824 width=0)",
      "        Filter: (last_seen > (now() - '7 days'::interval))"
    ]
  }
}

​
Error Responses

​
501
object
Admin Query Syntax Error - Invalid SQL syntax or database error
​
403
object
Insufficient Permissions - Not authorized as admin

​
Safety Features

  • Result Limit: All queries are automatically wrapped to limit results to 50 rows
  • Cost Analysis: Queries with estimated cost > 1,000,000 require ignoreCost: true
  • Read-Only: Only SELECT and EXPLAIN queries are supported
  • Semicolon Stripping: Trailing semicolons are removed to prevent injection

​
Caching

This endpoint is cached for 5 seconds.

​
Use Cases

  • Debug data issues
  • Analyze query performance
  • Extract custom reports
  • Investigate leaderboard calculations

Build docs developers (and LLMs) love

Get started for freeTalk to us