Finder Instances Ranking API

API Documentation

Complete reference for all endpoints with practical cURL examples.

Find instances

Find EC2 instances matching your requirements. Returns matching instances with top 3 recommendations by price, performance, and balanced criteria.

GET /api/finder

Basic usage (all parameters optional)

curl -s "https://go.runs-on.com/api/finder" | jq '.results | length'

Filter by region

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" | jq '.top3[0]'

Filter by multiple regions (comma-separated)

Returns only instances available in all specified regions.

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1,us-west-2" | jq '.results | length'

Filter by multiple regions (plus-separated)

Plus signs can also be used as separators.

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1+us-west-2" | jq '.results | length'

Filter by CPU range

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "cpu=2-4" | jq '.top3[0]'

Filter by RAM

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "cpu=2-4" \
  -d "ram=8" | jq '.top3[0]'

Filter by GPU

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "gpu=1-2" | jq '.results[0]'

Filter by architecture

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "arch=arm64" | jq '.top3[0]'

Filter by platform

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "platform=linux" | jq '.top3[0]'

Filter by instance family

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "family=m7" | jq '.results | length'

Filter by multiple families

curl -sG "https://go.runs-on.com/api/finder" \
  -d "region=us-east-1" \
  -d "family=m5,m7a" | jq '.results | length'

Query parameters

  • region - AWS region (e.g., us-east-1) or all (default: all, searches all regions). Multiple regions can be specified separated by comma or plus sign (e.g., us-east-1,us-west-2 or us-east-1+us-west-2). When multiple regions are specified, only instances available in all specified regions are returned.
  • cpu - CPU range in format min-max or single value (e.g., 2-4 or 4) or all (default: all)
  • ram - RAM in GB, format min-max or single value (e.g., 8-16 or 8) or all (default: all)
  • gpu - GPU count range in format min-max or single value (e.g., 1-2 or 1) or all (default: all)
  • passmark - PassMark score range (optional, format: min-max or single value)
  • arch - Architecture filter (optional, can be multiple): arm64, amd64, or x86_64
  • platform - Platform filter (optional, can be multiple): linux, linux/unix, or windows
  • family - Instance family or partial instance type filter (optional, comma or plus separated): Supports exact family names (e.g., m5), partial matching (e.g., m7 matches m7a, m7g, etc.), wildcard patterns (e.g., m5.* or m5.), or exact instance types (e.g., m5.large). Multiple families can be specified with commas or plus signs (e.g., m5,m7a or m5+m7a)

Response example

{
  "results": [
    {
      "instanceType": "m5.large",
      "instanceFamily": "m5",
      "vcpus": 2,
      "memoryGiB": 8,
      "avgSpotPrice": 0.029,
      "avgOnDemandPrice": 0.096,
      "cpuSpeed": 2500
    }
  ],
  "top3ByPrice": [...],
  "top3ByPerformance": [...],
  "top3": [...]
}

Get instance type pricing

Get detailed pricing information for a specific instance type or family.

GET /api/instances/{instanceType}

Get pricing for specific instance type

curl -sG "https://go.runs-on.com/api/instances/m7a.xlarge" | jq '.results[0]'

Get pricing for instance family

curl -sG "https://go.runs-on.com/api/instances/m7a" | jq '.results | length'

Filter by region and platform

curl -sG "https://go.runs-on.com/api/instances/m7a.large" \
  -d "region=us-east-1" \
  -d "platform=Linux/UNIX" | jq '.results[0]'

Filter by availability zone

curl -sG "https://go.runs-on.com/api/instances/m7a.xlarge" \
  -d "az=us-east-1b" \
  -d "platform=Linux/UNIX" | jq '.results[0]'

Response example

{
  "results": [
    {
      "timestamp": "2025-11-17 11:40:38",
      "region": "us-east-1",
      "az": "us-east-1b",
      "zoneId": "use1-az4",
      "instanceFamily": "m7a",
      "instanceType": "m7a.xlarge",
      "platform": "Linux/UNIX",
      "cpuModel": "AMD EPYC 9R14 (x86_64)",
      "vcpus": 4,
      "memoryGiB": 16,
      "gpus": 0,
      "cpuSpeed": 2887,
      "onDemandPrice": 0.23184,
      "spotPrice": 0.0867
    }
  ]
}

Calculate cost

Calculate the cost for a specific usage period.

POST /api/costs

Calculate on-demand cost

curl -X POST "https://go.runs-on.com/api/costs" \
  -H "Content-Type: application/json" \
  -d '{
    "startedAt": "2024-01-15T10:00:00Z",
    "instanceType": "m7a.large",
    "az": "us-east-1b",
    "region": "us-east-1",
    "arch": "x86_64",
    "platform": "Linux/UNIX",
    "instanceLifecycle": "on-demand"
  }' | jq .

Calculate spot cost

curl -X POST "https://go.runs-on.com/api/costs" \
  -H "Content-Type: application/json" \
  -d '{
    "startedAt": "2024-01-15T10:00:00Z",
    "instanceType": "m7a.xlarge",
    "az": "us-west-2a",
    "region": "us-west-2",
    "arch": "x86_64",
    "platform": "Linux/UNIX",
    "instanceLifecycle": "spot"
  }' | jq .

Request body parameters

  • startedAt - Start time (ISO 8601 format, required)
  • instanceType - Instance type (required)
  • az - Availability zone (required)
  • region - AWS region (required)
  • arch - Architecture (x86_64, arm64, required)
  • platform - Linux/UNIX or Windows (required)
  • instanceLifecycle - spot or on-demand (required)

Rate limiting

The API has no rate limits, but please be respectful of server resources. For high-volume usage, consider caching responses.

Home
RunsOn