API Reference

REST API

Query the pricing catalog, export filtered data, and manage price alerts. This reference is organized by resource so engineers can find endpoints, parameters, and request examples without reading product copy first.

Base URL

https://rateplane.com

Format

JSON responses, CSV exports

Coverage

8 documented endpoints

Authentication

Endpoints marked Auth required need an authenticated Rateplane session or supported API credential. Public catalog endpoints can be called without authentication, subject to global rate limits.

Need SDK examples?

TypeScript, Python, and direct HTTP usage are covered separately.

Open SDK docs

Endpoint Index

Method	Path	Resource	Access
GET	/api/instances	Catalog	Public
GET	/api/instances/:id	Catalog	Public
GET	/api/regions	Catalog	Public
GET	/api/export	Export	Authenticated
GET	/api/alerts	Price Alerts	Authenticated
POST	/api/alerts	Price Alerts	Authenticated
DELETE	/api/alerts/:id	Price Alerts	Authenticated
GET	/api/compare	Compare	Public

Catalog

Read normalized compute catalog data and region metadata.

Back to index

GET/api/instances

List instances from the normalized catalog with filtering and pagination.

Public

Parameter	Type	Required	Description
`q`	`string`	No	Full-text search across instance name, family, and description.
`provider`	`AWS \| AZURE \| GCP \| OCI`	No	Filter to a single cloud provider.
`region`	`string`	No	Region name, such as us-east-1, eastus, or us-central1.
`priceType`	`ON_DEMAND \| SPOT \| RESERVED_1YR \| RESERVED_3YR`	No	Price type to sort and filter against. Default: ON_DEMAND.
`familyCategory`	`GENERAL \| COMPUTE \| MEMORY \| STORAGE \| GPU \| HPC`	No	Instance family category.
`minVcpus`	`number`	No	Minimum vCPU count.
`maxVcpus`	`number`	No	Maximum vCPU count.
`minMemoryGb`	`number`	No	Minimum memory in GiB.
`maxMemoryGb`	`number`	No	Maximum memory in GiB.
`maxHourly`	`number`	No	Maximum on-demand hourly price in USD.
`page`	`number`	No	Page number, 1-based. Default: 1.
`pageSize`	`number`	No	Results per page. Default: 50, max: 200.

Example request

curl "https://rateplane.com/api/instances?provider=AWS&minVcpus=8&maxHourly=0.5&pageSize=10"

GET/api/instances/:id

Get a single instance offer by catalog ID.

Public

Example request

curl "https://rateplane.com/api/instances/aws-m7i.large-us-east-1"

GET/api/regions

List regions available in the catalog with display names.

Public

Example request

curl "https://rateplane.com/api/regions"

Export

Download filtered catalog data for spreadsheets, analysis, or internal tooling.

Back to index

GET/api/export

Export the current filtered catalog view as CSV. Accepts the same query parameters as /api/instances.

Auth required

Parameter	Type	Required	Description
`q`	`string`	No	Full-text search.
`provider`	`string`	No	Cloud provider.
`region`	`string`	No	Region name.
`priceType`	`string`	No	Price type.

Example request

curl -H "Cookie: next-auth.session-token=..." \
  "https://rateplane.com/api/export?provider=GCP&minVcpus=4" \
  -o instances.csv

Price Alerts

Create, list, and remove price threshold notifications.

Back to index

GET/api/alerts

List all price alerts for the authenticated user.

Auth required

Example request

curl -H "Cookie: next-auth.session-token=..." \
  "https://rateplane.com/api/alerts"

POST/api/alerts

Create a new price alert. A confirmation email is sent to the alert email address.

Auth required

Parameter	Type	Required	Description
`provider`	`AWS \| AZURE \| GCP \| OCI`	Yes	Cloud provider.
`instanceName`	`string`	Yes	Instance type name, such as m7i.large.
`instanceLabel`	`string`	Yes	Human-readable instance label.
`regionName`	`string`	Yes	Region identifier.
`regionLabel`	`string`	Yes	Human-readable region name.
`condition`	`BELOW \| ABOVE`	Yes	Trigger condition.
`targetPrice`	`number`	Yes	Target price in USD/hr.
`priceType`	`string`	No	Price type. Default: ON_DEMAND.
`email`	`string`	Yes	Email address for the alert notification.

Example request

curl -X POST -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=..." \
  -d '{"provider":"AWS","instanceName":"m7i.large","instanceLabel":"m7i.large","regionName":"us-east-1","regionLabel":"US East (N. Virginia)","condition":"BELOW","targetPrice":0.09,"email":"you@example.com"}' \
  "https://rateplane.com/api/alerts"

DELETE/api/alerts/:id

Delete a price alert.

Auth required

Example request

curl -X DELETE -H "Cookie: next-auth.session-token=..." \
  "https://rateplane.com/api/alerts/clx..."

Compare

Fetch selected catalog offers for side-by-side comparisons.

Back to index

GET/api/compare

Fetch multiple instances by ID for side-by-side comparison.

Public

Parameter	Type	Required	Description
`id`	`string[]`	Yes	One or more catalog offer IDs. Repeat the param: ?id=a&id=b.

Example request

curl "https://rateplane.com/api/compare?id=aws-m7i.large-us-east-1&id=azure-Standard_D4s_v5-eastus"

Rate Limits

Limits vary by plan and endpoint family. Use the values below for integration planning and handle 429 responses with retry backoff.

Plan	Catalog reads	Exports	Alerts
FREE	60 req/min	10/day	5 active
PRO	300 req/min	unlimited	100 active
ENTERPRISE	1,000 req/min	unlimited	1,000 active