Site Status API to Check Whether a Website Is Up or Down
Use a site status API to check HTTP reachability, status codes, redirects, regional outages, and the limits of one-time checks.
A site status API makes an HTTP request to a URL and reports what the checker observed: whether it connected, the HTTP status code, and often a reason phrase, redirect destination, response time, or TLS details. The result answers “was this URL reachable from this checker at this moment?” It does not prove that every visitor can access the site, and one request is not ongoing uptime monitoring.
For a quick check, send the target URL to a provider’s status endpoint, inspect the response, and apply a health rule that fits your service. A common rule is 2xx and 3xx responses are up and 4xx and 5xx responses are down, but that rule is provider-specific. RankNibbler documents that default for its HTTP monitor and also supports body-content and certificate checks (RankNibbler documentation).
What a site status API checks
Most status APIs perform some version of these steps:
- Resolve the hostname through DNS.
- Open a TCP connection and negotiate TLS for HTTPS.
- Send an HTTP request, usually GET or HEAD.
- Follow redirects if configured.
- Return reachability, the response code, and provider-specific metadata.
Geekflare’s documented POST /up example accepts a URL and optional followRedirect, and can check through a selected country proxy. Its response includes reachability, an HTTP status code, and a reason phrase (Geekflare Site Status API documentation). A regional result represents that checking location; it is not a measurement of all users.
One-off status lookup versus uptime monitoring
| Use case | What it does | What you must define |
|---|---|---|
| One-time API check | Returns an observation now | URL, timeout, redirect behavior, and health rule |
| Scheduled uptime monitoring | Repeats checks and sends alerts | Cadence, retries, consecutive-failure policy, and alert destinations |
| Company status API | Reports a provider’s published incidents and component state | Which provider’s status page you are querying |
Cloudflare’s status API is an example of the third category. Its summary endpoint reports Cloudflare’s components, unresolved incidents, and maintenance; it is not a test of your website (Cloudflare Status API). Cloudflare recommends automated clients use the API rather than scrape the HTML page and send an identifiable User-Agent.
How to call a status API
1. Choose the check contract
- Method and authentication: confirm GET or POST, API-key placement, and required headers.
- Redirects: decide whether the final destination or the first response is authoritative.
- Location: use a regional proxy when geography matters, and label the result with that region.
- Health rule: decide whether HTTP status alone is enough, or whether you need body text, a certificate check, or an application endpoint.
- Timeout and retries: set a bounded timeout and avoid turning transient failures into immediate incidents.
2. cURL example (Geekflare’s documented shape)
curl -X POST 'https://api.geekflare.com/up' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com","followRedirect":true}'Use the provider’s current endpoint and authentication details from its documentation. Do not treat this example as an independent benchmark.
3. Python
import requests
endpoint = "https://api.geekflare.com/up"
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"url": "https://example.com",
"followRedirect": True,
}
response = requests.post(endpoint, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)4. Node.js
const response = await fetch('https://api.geekflare.com/up', {
method: 'POST',
headers: {
'x-api-key': process.env.GEEKFLARE_API_KEY,
'content-type': 'application/json'
},
body: JSON.stringify({
url: 'https://example.com',
followRedirect: true
})
});
if (!response.ok) {
throw new Error(`Status API returned ${response.status}`);
}
console.log(await response.json());Interpreting the response
Normalize provider-specific fields into an internal record so dashboards and alerts do not depend on one vendor’s naming:
{
"target": "https://example.com",
"checked_at": "2026-10-01T12:00:00Z",
"checker_region": "us-east",
"reachable": true,
"http_status": 200,
"final_url": "https://www.example.com/",
"response_time_ms": 184,
"health": "up"
}Keep reachable separate from health. A server can respond with 200 while returning an error page, and a 404 may be expected for a deliberately missing resource. If content matters, check a stable marker or use a dedicated health endpoint. If certificate expiry matters, select a provider that exposes certificate validation.
“Down for everyone or just me?”
A single result cannot answer that globally. DNS propagation, routing, a firewall rule, an ISP outage, bot protection, or a regional deployment can make a site reachable from one network and unavailable from another. Run checks from the affected region and at least one independent region, then compare:
- DNS resolution and resolved address
- TCP/TLS connection errors
- HTTP status and redirect chain
- response time and timeout rate
- body or certificate validation, when configured
A country proxy can help identify regional blocking, but the result still describes the selected proxy rather than every visitor.
Build a reliable recurring check
- Check a lightweight, unauthenticated health URL.
- Run from the regions where users actually connect.
- Use a timeout shorter than your alerting interval.
- Retry transient network errors with exponential backoff.
- Require two or three consecutive failures before paging.
- Record the first failure, recovery time, status code, final URL, and checker region.
- Send alerts to the channel your on-call process uses.
Do not poll a provider more often than its documented quota. Geekflare describes one credit per check and additional credits when using a proxy; those terms can change, so verify current documentation before budgeting (Geekflare terms shown with the API). Domainee also documents per-IP limits for its keyless endpoint; check its live page before relying on it in production (Domainee documentation).
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 or 403 from the status API | Missing, expired, or misnamed API key | Check the provider’s required header or query parameter and rotate the key if needed. |
| Target returns 404 | The URL is reachable but the resource is absent | Decide whether that path is expected; use a known health path for availability checks. |
| Target returns 429 | Rate limiting by the target or checker | Reduce frequency, add backoff, and review both services’ quotas. |
| Timeout | Slow origin, blocked region, DNS issue, or overly short timeout | Compare regions, inspect DNS/TLS separately, and use bounded retries. |
| Redirect reported as down | Client does not follow redirects or the final host is blocked | Enable redirect following when appropriate and validate the final URL. |
| 200 but users see an error | HTTP status does not represent application health | Validate response content or call a purpose-built health endpoint. |
| Different results by region | CDN, geo-routing, firewall, or regional outage | Store the checker location with every result and investigate the affected region. |
Performance, reliability, and cost
- Latency: total time includes DNS, connection setup, TLS, redirects, and origin processing. Record response time when the provider supplies it.
- False positives: one timeout is weak evidence. Retries and consecutive-failure thresholds reduce noisy alerts.
- Coverage: one vantage point cannot represent all customers. Choose regions deliberately.
- Request cost: quotas, proxy surcharges, failed-request billing, and retention differ by provider. Recheck live terms before publishing a budget.
- Security: never place private credentials in a public status URL. Use a safe unauthenticated endpoint or provider-supported headers.
- Load: probe a lightweight endpoint rather than a large homepage, and coordinate polling with your provider’s limits.
Or skip the browser setup
If your next step is to inspect what a reachable page actually looks like, ScreenshotNeo captures a URL through one HTTP request. It is a screenshot API, so it does not replace a status check or recurring monitor, but it can provide visual evidence after your reachability check.
Before capture, ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for all capture options, including full-page shots, element selectors, waits, custom headers, cookies, blocking rules, caching, PDFs, async jobs, bulk capture, and signed links.
Create a free ScreenshotNeo account with 1,000 screenshots each month and no card required.
FAQ
Does an HTTP 200 guarantee the site works?
No. It only shows that the checker received a 200 response. Add body or application checks when a generic success page could hide an outage.
Should I use GET or HEAD?
Follow the provider’s documented method. GET exercises more of the application and is often more representative; HEAD is lighter when the origin implements it correctly.
How often should checks run?
Choose a cadence based on detection needs, provider limits, and acceptable load. Define retries and consecutive failures before sending alerts.
Can a status API test a private staging site?
Only if the checker can reach it and you provide supported authentication or network access. Do not expose sensitive credentials in a public URL.
What is the difference between a status API and a status page API?
A status API probes a target URL. A status-page API publishes a company’s declared component state, incidents, and maintenance, such as Cloudflare’s documented summary endpoint.
