API Reference

Complete endpoint documentation for the RefineX signals API.

Base URL: https://api.refinex.io

Auth: X-API-Key header

Endpoints

GET/v1/health

Liveness check

GET/v1/signals/active

Single best action (autoscaler-friendly)— Primary endpoint

GET/v1/signals/summary

Aggregate view of current opportunities

GET/v1/signals

List all active signals (paginated)

Signal Types

↗Spot Arbitrage(94%)

Spot Arbitrage

Spot price is significantly lower than on-demand (>50% savings)

Actions: buy_spot, wait, fallback_on_demand

TTL: 600 seconds (10 min)

!Interruption Risk(87%)

Interruption Risk

Spot instance likely to be interrupted soon (based on price volatility)

Actions: migrate_spot, fallback_on_demand, checkpoint_now

TTL: 300 seconds (5 min)

GET /v1/signals/active

Returns the single best action for a specific cloud/region/instance_type combination. Designed for autoscalers that want ONE answer: "What should I do right now?"

Parameters

cloudrequired • string • Cloud provider (aws, gcp, azure)

regionrequired • string • Region (e.g., us-east-1)

instance_typerequired • string • Instance type (e.g., c7g.xlarge)

fallbackoptional • string • on_demand | wait | none (default: on_demand)

Example

# Request
GET https://api.refinex.io/v1/signals/active?cloud=aws&region=us-east-1&instance_type=c7g.xlarge
X-API-Key: sk_live_...

# Response
{
  "action": "buy_spot",
  "signal": {
    "signal_id": "01956789-abcd-7000-8000-123456789abc",
    "type": "spot_arbitrage",
    "timestamp": "2026-01-13T15:23:45Z",
    "source": {
      "cloud": "aws",
      "region": "us-east-1",
      "availability_zone": "us-east-1a"
    },
    "asset": {
      "instance_type": "c7g.xlarge",
      "vcpu": 4,
      "memory_gb": 8,
      "current_spot_price": 0.0425,
      "on_demand_price": 0.1445
    },
    "action": "buy_spot",
    "expected_value": {
      "savings_percent": 70.6,
      "savings_usd_per_hour": 0.102,
      "risk_adjusted_savings": 0.098
    },
    "confidence": 0.94,
    "ttl": 600,
    "expires_at": "2026-01-13T15:33:45Z"
  },
  "alternatives": [
    {
      "availability_zone": "us-east-1b",
      "current_spot_price": 0.0445,
      "savings_percent": 69.2,
      "confidence": 0.91
    }
  ]
}

GET /v1/signals/summary

Returns aggregate view of current opportunities. Useful for dashboards and CI/CD systems that want to know "How many good deals exist right now?"

Example

# Request
GET https://api.refinex.io/v1/signals/summary?cloud=aws&min_savings=50&confidence_min=0.80
X-API-Key: sk_live_...

# Response
{
  "timestamp": "2026-01-13T15:30:00Z",
  "summary": {
    "total_signals": 347,
    "spot_arbitrage": 312,
    "interruption_risk": 35,
    "avg_savings_percent": 68.4,
    "avg_confidence": 0.87
  },
  "by_cloud": {
    "aws": {
      "signals": 201,
      "avg_savings_percent": 71.2,
      "top_instance_types": [
        {
          "instance_type": "c7g.xlarge",
          "signals": 45,
          "avg_savings": 70.6
        }
      ]
    }
  },
  "ttl": 300,
  "next_update": "2026-01-13T15:35:00Z"
}

Rate Limits

100

Free tier

requests/min

1000

Starter

requests/min

10K

Pro

requests/min

100K

Enterprise

requests/min