Skip to main content

​
API Reference

Base URL for all API requests: 
https://api.polyhistorical.com/v1

​
Authentication

All endpoints require an API key passed in the X-API-Key header. See Authentication for details.

​
Request format

  • All requests use standard query parameters
  • Responses are JSON
  • Timestamps are ISO 8601 format (UTC)
  • Pagination uses limit and offset parameters

​
Response format

All responses follow this structure: Success (market list): 
{
  "markets": [...],
  "total": 1462,
  "limit": 50,
  "offset": 0
}
Success (single market): 
{
  "slug": "btc-updown-5m-1774581000",
  "market_id": "1724470",
  "market_type": "5m",
  ...
}
Success (snapshots): 
{
  "market": { ... },
  "snapshots": [...],
  "total": 45,
  "limit": 100,
  "offset": 0
}
Error: 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error description"
  },
  "timestamp": "2026-03-27T12:00:00Z"
}

​
Common error codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request parameters
UNAUTHORIZED401Missing or invalid API key
TIER_ACCESS_DENIED403Feature requires a higher plan
RESOURCE_NOT_FOUND404Market or resource not found
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

​
Endpoints

MethodEndpointDescription
GET/v1/marketsList markets with filtering and pagination
GET/v1/markets/{slug}Get a single market by slug
GET/v1/markets/{slug}/snapshotsGet snapshots for a market