TanStack Query

Status page fetching with TanStack Query — useQuery guide

Fetch your PulseAPI status endpoint with useQuery. Cache, refetch on focus, interval polling, and SSE realtime — all in a typed React hook.

Start monitoring free Build your own via API

Three ways to ship a status page for TanStack Query

Pick the level of control you need — zero-code, low-code, or full headless.

Hosted

Add your TanStack Query endpoint, point a CNAME at status.yourdomain.com, done. Works in 5 minutes.

Headless

Use our public API to build your own UI inside your TanStack Query app. Full control over design and branding.

See the API

Embedded badges

Drop SVG uptime and status badges into your README or landing page. Auto-updates every 5 minutes.

Drop this health endpoint into your TanStack Query app

Copy, paste, point PulseAPI at the URL. Returns 200 when healthy, 503 when degraded.

app/status/use-status-query.ts

import { useQuery } from '@tanstack/react-query'

interface StatusData {
  page: { title: string; customDomain: string | null }
  overallStatus: 'operational' | 'degraded' | 'down' | 'maintenance' | 'unknown'
  endpoints: Array<{
    id: string
    name: string
    status: string
    uptime24h: number
    avgResponseTime: number
  }>
}

export const useStatusQuery = (slug: string) =>
  useQuery<StatusData>({
    queryKey: ['status', slug],
    queryFn: async () => {
      const r = await fetch(`https://api.pulseapi.tech/status/${slug}`)
      if (!r.ok) throw new Error(`Status ${r.status}`)
      return r.json()
    },
    staleTime: 30_000,
    refetchInterval: 30_000,
    refetchOnWindowFocus: true,
  })

Use a 30-second staleTime and refetchInterval to match our SSE heartbeat. For realtime updates without polling, pair this hook with our /sse/status/:slug stream and use queryClient.setQueryData to patch the cache on events.

What breaks in TanStack Query apps — and how to catch it

Stale status on long-lived tabs

A dashboard left open overnight shows a green banner while production is actually down. refetchInterval + refetchOnWindowFocus keeps the cache honest.

Flash of incorrect content during revalidation

placeholderData + keepPreviousData lets you keep showing the last good status while a refetch is in flight — no flicker between "operational" and loading skeleton.

Too many parallel requests from nested components

Multiple components calling useStatusQuery would each fire a request — React Query deduplicates by queryKey so only one in-flight fetch exists per slug.

Headless angle

Don't like our status page? Build your own in TanStack Query.

Our API returns the same data our hosted UI consumes. Full OpenAPI spec documented at api.pulseapi.tech/docs.

components/StatusBanner.tsx — show an inline banner in your app whenever PulseAPI reports a degraded or down state.

import { useStatusQuery } from './use-status-query'

export function StatusBanner({ slug }: { slug: string }) {
  const { data, isLoading, error } = useStatusQuery(slug)

  if (isLoading) return <div className="skeleton" />
  if (error) return null
  if (!data) return null
  if (data.overallStatus === 'operational') return null

  return (
    <a href={`https://${data.page.customDomain}`} className="banner">
      {data.overallStatus === 'down' ? 'Service disruption' : 'Degraded service'}
      {' — '}
      {data.endpoints.filter((e) => e.status !== 'operational').length} affected
    </a>
  )
}

Explore the API

TanStack Query monitoring — FAQ

How do I combine useQuery with SSE for realtime updates?

Open an EventSource to /sse/status/:slug in a useEffect, and on each event call queryClient.setQueryData(["status", slug], to merge event patches into the existing cache entry. This keeps useQuery subscribers updated without polling.

Does this work with TanStack Query v4 and v5?

Both. In v4 use cacheTime, in v5 it is renamed gcTime. isLoading in v5 is strictly "first load"; use isPending + isFetching if you want any in-flight indicator.

Can I prefetch status on the server with Next.js or Remix?

Yes. Call queryClient.prefetchQuery in a server component or loader, wrap your tree in HydrationBoundary (v5) or Hydrate (v4) with dehydrated state. Your useStatusQuery hook reads from the hydrated cache on first render — zero client-side flicker.

Is my org API key safe to use in useQuery?

No — any key in browser JS is public. The public status endpoint needs no auth; only use org API keys on the server. Proxy through a backend route (/api/status) and call that proxy from useQuery if you need auth.

Start monitoring your TanStack Query app in 5 minutes

Free tier. No credit card. Add your endpoint and get alerts when it breaks.

Start free View other frameworks