SDKs & APIs

Rateplane SDKs

Official TypeScript and Python clients for the Rateplane API. Access live multi-cloud pricing for AWS, Azure, and GCP programmatically — in your CI pipeline, cost scripts, dashboards, and internal tools.

Zero dependencies

Both SDKs use only stdlib / native fetch. No bloat.

Fully typed

Complete TypeScript types. Python type hints throughout.

Free for catalog reads

No Pro plan needed. Catalog APIs are free with any account.

Plans & rate limits

API access by plan

All plans include API access to the public pricing catalog. Create an API key at Dashboard → API Keys. No Pro plan required for catalog reads.

Plan	API keys	Requests / min	Bulk endpoint
Starter (free)	2	60	✓
Pro	20	600	✓
Enterprise	100	6,000	✓

TypeScript SDK

rateplane-sdk

npm

Works in Node.js 18+ and all modern browsers. Uses native fetch — no dependencies.

Installation

bash — npm

npm install rateplane-sdk

bash — pnpm

pnpm add rateplane-sdk

bash — yarn

yarn add rateplane-sdk

Quick start

typescript

import { Rateplane } from "rateplane-sdk";

const rp = new Rateplane({ apiKey: "rp_live_..." });

// List AWS instances with 8+ vCPUs under $0.50/hr
const result = await rp.instances.list({
  provider: "AWS",
  minVcpus: 8,
  maxHourly: 0.50,
  pageSize: 100,
});

console.log(`Found ${result.total} instances`);
for (const inst of result.data) {
  console.log(
    inst.name,
    inst.vcpus, "vCPUs",
    inst.memoryGb, "GiB",
    `$${inst.pricing.onDemand}/hr`,
  );
}

Common patterns

Get a single instance by catalog ID

typescript

const inst = await rp.instances.get("aws-m7i.large-us-east-1");
console.log(inst.vcpus, inst.memoryGb, inst.pricing.onDemand);

Download the full AWS catalog in one request

typescript

const { data, total, truncated } = await rp.instances.getAll({ provider: "AWS" });
if (truncated) {
  console.warn(`Only ${data.length} of ${total} rows returned — add filters`);
}

Compare instances side-by-side

typescript

const instances = await rp.instances.compare([
  "aws-m7i.large-us-east-1",
  "azure-Standard_D4s_v5-eastus",
  "gcp-n2-standard-4-us-central1",
]);
instances.forEach((i) => {
  console.log(i.provider.name, i.name, i.pricing.onDemand);
});

Export filtered catalog to CSV

typescript

import { writeFileSync } from "fs";

const csv = await rp.instances.exportCsv({
  provider: "AWS",
  minVcpus: 16,
  priceType: "SPOT",
});
writeFileSync("spot-instances.csv", csv);

Use expression filters

typescript

// GPU instances on AWS with at least 4 GPUs under $3/hr
const result = await rp.instances.list({
  expr: "gpu>=4 price<3",
  provider: "AWS",
});

Error handling

typescript

import { Rateplane, RateplaneError } from "rateplane-sdk";

try {
  const inst = await rp.instances.get("invalid-id");
} catch (err) {
  if (err instanceof RateplaneError) {
    console.error(`API error ${err.status}: ${err.message}`);
  }
}

Method reference

rp.instances.list(params?)

List instances from the catalog with filtering and pagination. Returns up to 200 rows per page.

Returns: Promise<ListInstancesResponse>

rp.instances.get(id)

Get a single instance by catalog ID (e.g. aws-m7i.large-us-east-1).

Returns: Promise<Instance>

rp.instances.getAll(params?)

Download all matching instances in one request (up to 5,000 rows). Check the truncated field.

Returns: Promise<GetAllInstancesResponse>

rp.instances.compare(ids[])

Fetch multiple instances side-by-side by catalog ID. Pass up to 4 IDs.

Returns: Promise<Instance[]>

rp.instances.exportCsv(params?)

Export the filtered catalog as a CSV string. Same params as list().

Returns: Promise<string>

Python SDK

rateplane-python

PyPI

Pure Python 3.8+ with no dependencies. Uses only urllib from the standard library.

Installation

bash

pip install rateplane-python

Quick start

python

from rateplane import Rateplane

rp = Rateplane(api_key="rp_live_...")

# List AWS instances with 8+ vCPUs under $0.50/hr
result = rp.instances.list(
    provider="AWS",
    min_vcpus=8,
    max_hourly=0.50,
    page_size=100,
)

print(f"Found {result['total']} instances")
for inst in result["data"]:
    print(
        inst["name"],
        inst["vcpus"], "vCPUs",
        inst["memoryGb"], "GiB",
        f"$" + str(inst['pricing']['onDemand']) + "/hr",
    )

Common patterns

Get a single instance

python

inst = rp.instances.get("aws-m7i.large-us-east-1")
print(inst["vcpus"], inst["memoryGb"], inst["pricing"]["onDemand"])

Download the full GCP catalog

python

result = rp.instances.get_all(provider="GCP")
if result["truncated"]:
    print(f"Warning: only {result['returned']} of {result['total']} rows returned")
instances = result["data"]

Find cheapest spot instances with Pandas

python

import pandas as pd
from rateplane import Rateplane

rp = Rateplane(api_key="rp_live_...")

result = rp.instances.get_all(provider="AWS", price_type="SPOT", min_vcpus=4)
df = pd.DataFrame(result["data"])

# Expand nested pricing dict
df["spot_price"] = df["pricing"].apply(lambda p: p.get("spot"))
df = df.dropna(subset=["spot_price"])

print(df[["name", "vcpus", "memoryGb", "spot_price"]]
    .sort_values("spot_price")
    .head(10))

Export to CSV

python

csv_data = rp.instances.export_csv(provider="AWS", price_type="SPOT")
with open("spot-instances.csv", "w") as f:
    f.write(csv_data)

Error handling

python

from rateplane import Rateplane, RateplaneError

try:
    inst = rp.instances.get("invalid-id")
except RateplaneError as err:
    print(f"API error {err.status}: {err}")

Method reference

rp.instances.list(**kwargs)

List instances with filtering and pagination. All params are keyword-only with snake_case names.

Returns: dict (data, total, page, pageSize, totalPages)

rp.instances.get(instance_id)

Get a single instance dict by catalog ID.

Returns: dict

rp.instances.get_all(**kwargs)

Download all matching instances in one request (up to 5,000 rows).

Returns: dict (data, total, returned, truncated)

rp.instances.compare(instance_ids)

Fetch multiple instances side-by-side. Pass a list of catalog IDs.

Returns: list[dict]

rp.instances.export_csv(**kwargs)

Export the filtered catalog as a CSV string.

Returns: str

REST API

Direct HTTP access

All SDK methods are thin wrappers around public HTTP endpoints. You can use curl, wget, or any HTTP client directly.

Base URL

https://rateplane.com

Authentication

Pass your API key as Authorization: Bearer rp_live_.... Omit the header for unauthenticated access (global rate limits apply).

List instances (paginated)

bash

curl "https://rateplane.com/api/instances?provider=AWS&minVcpus=8&maxHourly=0.5" \
  -H "Authorization: Bearer rp_live_..."

Get a single instance

bash

curl "https://rateplane.com/api/instances/aws-m7i.large-us-east-1" \
  -H "Authorization: Bearer rp_live_..."

Bulk download (up to 5,000 rows)

bash

curl "https://rateplane.com/api/instances/all?provider=GCP" \
  -H "Authorization: Bearer rp_live_..." \
  | jq '.data | length'

Export to CSV

bash

curl "https://rateplane.com/api/export?provider=AWS&minVcpus=16&priceType=SPOT" \
  -H "Authorization: Bearer rp_live_..." \
  -o spot-instances.csv

Query parameters

Parameter	Type	Description
q	string	Full-text search across name, family, description
provider	AWS \| AZURE \| GCP \| OCI	Filter to one cloud provider
region	string	Region name (e.g. us-east-1, eastus, us-central1)
priceType	ON_DEMAND \| SPOT \| RESERVED_1YR \| RESERVED_3YR	Default: ON_DEMAND
familyCategory	GENERAL \| COMPUTE \| MEMORY \| STORAGE \| GPU \| HPC	Instance family category
minVcpus	number	Minimum vCPU count
maxVcpus	number	Maximum vCPU count
minMemoryGb	number	Minimum memory in GiB
maxMemoryGb	number	Maximum memory in GiB
maxHourly	number	Maximum on-demand hourly price (USD)
expr	string	Expression filter, e.g. vcpu>=8 memory<=32
currency	string	ISO 4217 currency code (default: USD)
page	number	Page number, 1-based (list only)
pageSize	number	Results per page, max 200 (list only)

Get started

Ready to build?

Create an API key

Free with any account. No Pro plan needed for catalog access.

Full API reference

All endpoints, response schemas, authentication, and rate limits.