Skip to main content

​
Endpoint

GET /api/cooldown-status
Returns the current status of the refresh cooldown, including whether a cooldown is active and how many minutes remain before the next refresh is allowed.

​
Request

This endpoint does not require any parameters.
cURL
curl https://emptyclassroom-production.up.railway.app/api/cooldown-status

​
Response

​
in_cooldown
boolean
required
Whether the refresh endpoint is currently in cooldown
​
remaining_minutes
number
required
Number of minutes remaining in the cooldown period. Returns 0 if not in cooldown.

​
Response Examples

​
Cooldown Active

{
  "in_cooldown": true,
  "remaining_minutes": 15.3
}

​
Cooldown Expired

{
  "in_cooldown": false,
  "remaining_minutes": 0
}

​
No Previous Refresh

If no refresh has ever been performed (fresh app state): 
{
  "in_cooldown": false,
  "remaining_minutes": 0
}

​
Behavior

​
Cooldown Calculation

The endpoint calculates cooldown status by:
  1. Retrieving the last refresh timestamp from Redis (classrooms:last_refresh key)
  2. Comparing it against the current time in America/New_York timezone
  3. Checking if less than 30 minutes have elapsed
  4. Calculating the remaining time if in cooldown

​
Return Values

Conditionin_cooldownremaining_minutes
Less than 30 minutes since last refreshtrueTime left (e.g., 15.3)
30+ minutes since last refreshfalse0
No previous refresh existsfalse0
Error reading timestampfalse0

​
Error Handling

This endpoint is designed to be resilient and never returns an error response. If there’s an issue reading the cooldown status from Redis:
  • Returns in_cooldown: false and remaining_minutes: 0
  • Logs the error server-side
  • Allows the caller to proceed (fail-open behavior)
Error Fallback
{
  "in_cooldown": false,
  "remaining_minutes": 0
}
The fail-open behavior ensures the UI remains functional even if Redis is temporarily unavailable. The actual /api/refresh endpoint will still enforce the cooldown if possible.

​
Example Usage

​
Check Before Refresh

JavaScript
const checkCooldown = async () => {
  const response = await fetch(
    'https://emptyclassroom-production.up.railway.app/api/cooldown-status'
  );
  const status = await response.json();
  
  if (status.in_cooldown) {
    console.log(`Cooldown active. Wait ${status.remaining_minutes.toFixed(1)} minutes`);
    return false;
  } else {
    console.log('Refresh available');
    return true;
  }
};

// Use it
if (await checkCooldown()) {
  // Proceed with refresh
}

​
Display Cooldown Timer

React Example
import { useEffect, useState } from 'react';

function RefreshButton() {
  const [cooldown, setCooldown] = useState({ in_cooldown: false, remaining_minutes: 0 });
  
  useEffect(() => {
    const checkCooldown = async () => {
      const res = await fetch(
        'https://emptyclassroom-production.up.railway.app/api/cooldown-status'
      );
      const data = await res.json();
      setCooldown(data);
    };
    
    checkCooldown();
    const interval = setInterval(checkCooldown, 10000); // Check every 10s
    
    return () => clearInterval(interval);
  }, []);
  
  return (
    <button disabled={cooldown.in_cooldown}>
      {cooldown.in_cooldown 
        ? `Wait ${Math.ceil(cooldown.remaining_minutes)} min` 
        : 'Refresh Data'
      }
    </button>
  );
}
Python
import requests
import time

def wait_for_cooldown():
    """Wait until cooldown expires before refreshing"""
    while True:
        response = requests.get(
            'https://emptyclassroom-production.up.railway.app/api/cooldown-status'
        )
        status = response.json()
        
        if not status['in_cooldown']:
            print('Cooldown expired, ready to refresh')
            break
        
        minutes = status['remaining_minutes']
        print(f'Cooldown active: {minutes:.1f} minutes remaining')
        time.sleep(60)  # Check again in 1 minute
cURL
curl https://emptyclassroom-production.up.railway.app/api/cooldown-status

​
Use Cases

  • UI Button States: Enable/disable refresh buttons based on cooldown status
  • Countdown Timers: Display remaining cooldown time to users
  • Automated Scripts: Wait for cooldown to expire before refreshing
  • Error Prevention: Avoid 429 errors by checking cooldown first

​
Best Practices

Poll this endpoint instead of the /api/refresh endpoint if you need to monitor when refresh becomes available. This endpoint is lightweight and doesn’t trigger any data updates.
For the best user experience, check this endpoint before allowing users to click a refresh button, and display the remaining time if in cooldown.

​
Notes

  • The remaining_minutes value is a floating-point number with decimal precision
  • Round or format the value appropriately for display (e.g., “Wait 15 minutes”)
  • The cooldown is shared globally - one user’s refresh affects all users
  • The cooldown is tied to the last successful refresh, not failed attempts

Build docs developers (and LLMs) love

Get started for freeTalk to us