API Endpoints Reference
Complete RESTful API reference for the US Lottery API engine. All requests are served over HTTPS with JSON response payloads.
Base Endpoint URL
HTTPS Onlyhttps://uslotteryapi.com/api/v1
Available REST Endpoints
GET/api/v1/health
View Specification →Verify the API service is running. Useful for uptime monitoring and load balancer health checks.
GET/api/v1/states
View Specification →Retrieve a list of supported US states and fetch state-specific lottery game catalogs.
GET/api/v1/lotteries/analytics
View Specification →Programmatically query 30-day ball frequencies, Hot/Cold numbers, sum range distributions, top pair combinations, overdue numbers, and Chi-Square randomness test metrics.
HTTP Status Codes Breakdown
US Lottery API relies on conventional HTTP response codes to indicate request outcome:
| Code | Status | Meaning & Recommended Action |
|---|---|---|
| 200 | OK | Request succeeded. Payload contains requested data. |
| 400 | Bad Request | Invalid query parameters or unsupported game slug. Check syntax. |
| 401 | Unauthorized | Missing or invalid x-api-key header. Verify API token. |
| 429 | Too Many Requests | Rate limit exceeded for your tier. Exponential backoff recommended. |
| 500 | Internal Server Error | Unexpected API engine error. Contact support if issue persists. |
Standard Error Payload Schema
Non-200 responses return a JSON object with details on why the request failed:
Error Response JSON
// Standard JSON Error Response Payload
{
"status": "error",
"code": 401,
"error_type": "UNAUTHORIZED",
"message": "Invalid or missing API key in 'x-api-key' header.",
"timestamp": "2026-08-03T01:50:00Z",
"request_id": "req_9f8e7d6c5b4a"
}