Provider API

The provider API lets you run your nodes from your own scripts and monitoring:

• add a node and get the command that installs the agent,
• see what each node is doing, with live GPU load, temperature and power,
• take a node off the market when you need it (for your own work, or because it was rented somewhere else) and put it back,
• set its price,
• read what you earned, by day and by node.

It uses the same prlc_ key as the Inference API, with the nodes scope, sent as a bearer token:

Authorization: Bearer prlc_your_key_here

Base URL: https://paraloncloud.com/api/v1

Endpoints

Method	Path	What it does
GET	/nodes	List your nodes, with state, price, live metrics and the current rental
GET	/nodes/{id}	One node
POST	/nodes	Add a node; answers its install command
GET	/nodes/{id}/command	The install command of a node, again
PATCH	/nodes/{id}	Change available, price_per_hour, spot or name
POST	/nodes/{id}/reclaim	Spot node: take the machine back, a spot rental stops in 2 minutes
GET	/earnings?days=30	Earnings by day and by node, and the balance you can withdraw

Deleting a node, requesting a payout and changing where payouts go are not in the API; they stay on the site.

The nodes scope

A key cannot touch your nodes until you give it the nodes scope: in the Console, API keys, tick My nodes when you create a key, or turn it on in a key's settings. A key without it gets 403 insufficient_scope.

In an organization, only a member allowed to manage nodes (Owner or Admin) can give a key this scope, and the key acts on the organization's nodes. What the key adds or changes is in the organization's activity log, under the person who made the key; if that person's role changes to one that cannot manage nodes, their keys lose the scope.

Payouts are never reachable by API. A leaked key could still change your prices or availability, or read a node's install command, so keep it private, use a key only for this, and revoke it if in doubt.

List your nodes

curl https://paraloncloud.com/api/v1/nodes \
  -H "Authorization: Bearer $PARALON_API_KEY"

{
  "nodes": [
    {
      "id": "0759f45f-b60e-4814-854b-9b12fe87228b",
      "name": "rig-1",
      "type": "gpu",
      "online": true,
      "state": "rented",
      "available": true,
      "spot": false,
      "gpus": [{ "model": "NVIDIA GeForce RTX 4090", "vram_mb": 24564 }],
      "price": {
        "currency": "USD", "unit": "hour", "spot": false,
        "default": 0.54, "min": 0.27, "max": 1.62,
        "custom": 0.52, "renter_pays": 0.52
      },
      "verification": { "status": "verified", "verified_at": "2026-10-20T14:31:03Z", "error": "" },
      "rent_ready": true,
      "rent_ready_reason": "jupyter present and digest approved",
      "inference_enabled": true,
      "reputation": { "tier": "proven", "score": 86 },
      "last_seen": "2026-10-21T17:49:43Z",
      "metrics": {
        "at": "2026-10-21T17:49:50Z",
        "gpus": [{ "utilization_pct": 100, "temperature_c": 69, "power_w": 449.5, "vram_used_mb": 2525, "vram_free_mb": 21614 }],
        "cpu_pct": 100, "memory_used_mb": 4782, "memory_free_mb": 59199
      },
      "rental": {
        "id": "be52a3aa-3d23-43d3-a31c-5b332808291a",
        "status": "running",
        "started_at": "2026-10-20T16:58:35Z",
        "ends_at": null,
        "price_per_hour": 0.52
      }
    }
  ]
}

One node: GET /nodes/{id} answers the same object. A node that is not yours, or does not exist, answers 404 node_not_found.

The node object

Field	Meaning
id, name, type	The node; type is gpu, cpu or mac
online	The agent is connected now
state	One word for what a renter sees now (table below)
available	On the market (false after you took it off)
spot	A spot node: discounted and reclaimable
gpus	Each GPU's model and memory
price.default	The platform's default price for these GPUs, per hour for the whole node
price.min, price.max	The range a custom price must be in (50% to 300% of the default); absent on spot
price.custom	Your price, or null when the node is on the default
price.renter_pays	What a new rental pays per hour (your price, or the default; the spot price on spot)
verification	The GPU check: verified, verifying, failed or unverified, and why it failed
rent_ready, rent_ready_reason	Whether a rental can start now, and why not
inference_enabled	Whether the node serves the inference API between rentals
reputation	tier and, once proven, a score out of 100 (Reputation); absent on spot
last_seen	The last time the agent was heard from
metrics	The last live reading (below), or null
rental	The rental on the node now (id, status, started_at, ends_at, price_per_hour, and reclaim_at during a reclaim), or null. The renter is never shown

state	Meaning
available	Online, verified, ready, and on the market
rented	A rental is running on it
paused	You took it off the market (available is false)
not_verified	The GPU check has not passed (verification.error says why)
not_ready	Online but cannot take a rental yet (rent_ready_reason says why)
offline	The agent is not connected

Live metrics

metrics is the last reading your agent sent, about once a minute: for each GPU the load (utilization_pct), temperature_c, power_w, vram_used_mb and vram_free_mb, and for the machine cpu_pct, memory_used_mb and memory_free_mb; at is when it was read. It is null when the node has sent nothing in the last few minutes. Poll GET /nodes (once a minute is plenty) to feed your own dashboards or alerts.

Add a node

curl -X POST https://paraloncloud.com/api/v1/nodes \
  -H "Authorization: Bearer $PARALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "rig-2", "type": "gpu", "os": "linux"}'

{
  "node_id": "7c1e…",
  "docker_command": "docker run … ghcr.io/paraloncloud/agent:latest",
  "node": { "id": "7c1e…", "name": "rig-2", "state": "offline", "…": "…" }
}

Field	Required	Values
name	yes	Your label, up to 100 characters
type	no	gpu (default), cpu or mac
os	no	linux (default) or windows
available	no	true (default): on the market as soon as it is ready
spot	no	true for a spot node (GPU only)

Run docker_command on the machine: the node comes online and goes through the GPU check like any other. See Add a Node for what the machine needs. A key can add up to 20 nodes an hour.

To get the command of a node again:

curl https://paraloncloud.com/api/v1/nodes/$NODE_ID/command \
  -H "Authorization: Bearer $PARALON_API_KEY"

{ "node_id": "7c1e…", "docker_command": "docker run -d …" }

The command holds the node's token: whoever has it can connect a machine as that node. Treat it like a password.

Change a node

PATCH /nodes/{id} takes any of these fields; send only what you change. The answer is the node as it is now, in the shape above.

Field	Values	Effect
available	true / false	On or off the market. Off stops new rentals at once; a rental already running goes on to its end
price_per_hour	a number in USD, or null	Your price for the whole node, between price.min and price.max; null goes back to the default
spot	true / false	Make it a spot node or back to on demand. Refused (409) while the node is rented
name	a string	Rename it

Take a node off the market, and back

curl -X PATCH https://paraloncloud.com/api/v1/nodes/$NODE_ID \
  -H "Authorization: Bearer $PARALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"available": false}'

{"available": true} puts it back. If you list the same machine on another marketplace, call this when it is rented there, so it is never rented twice.

Set the price

curl -X PATCH https://paraloncloud.com/api/v1/nodes/$NODE_ID \
  -H "Authorization: Bearer $PARALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price_per_hour": 0.64}'

The price is what the renter pays per hour for the whole node, in US dollars; your share is that minus the platform fee. Outside price.min–price.max the answer is 400 with the allowed range. A rental already running keeps the price it started at. A spot node always rents at the spot price and takes no custom price. {"price_per_hour": null} goes back to the default. See Node Pricing.

Spot and name

curl -X PATCH https://paraloncloud.com/api/v1/nodes/$NODE_ID \
  -H "Authorization: Bearer $PARALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spot": true, "name": "rig-1 (spot)"}'

Turning spot on clears your custom price: a spot node rents at the default price minus the spot discount.

Take a spot node back

On a spot node you can take the machine back from a running spot rental, the same as In use on the site:

curl -X POST https://paraloncloud.com/api/v1/nodes/$NODE_ID/reclaim \
  -H "Authorization: Bearer $PARALON_API_KEY"

{
  "id": "…", "state": "rented", "available": false, "…": "…",
  "reclaim": { "rental_id": "…", "reclaim_at": "2026-10-21T18:02:00Z" }
}

Rentals and inference go off. A spot rental on the node stops at reclaim_at, two minutes later; the renter is told and billed only until it stops. A rental that started before the node was spot is not interrupted (reclaim.message says so). On a node that is not spot the answer is 409. Put the node back with PATCH {"available": true}.

Earnings

curl "https://paraloncloud.com/api/v1/earnings?days=30" \
  -H "Authorization: Bearer $PARALON_API_KEY"

{
  "currency": "USD",
  "days": [
    { "day": "2026-10-20", "rentals": 1.677, "inference": 0, "total": 1.677,
      "nodes": [{ "node_id": "0759f45f-…", "name": "rig-1", "rentals": 1.677 }] },
    { "day": "2026-10-21", "rentals": 0, "inference": 0, "total": 0, "nodes": [] }
  ],
  "total": 17.2407,
  "earnings_balance": 115.5472,
  "running_rentals_billed_before_fee": 12.9225
}

Field	Meaning
days	One entry per UTC day for the last days days (1 to 366, default 30), oldest first
days[].rentals	Your share of rentals that ended that day, after the platform fee; nodes splits it by node
days[].inference	Your share of inference served that day, for the account as a whole (not split by node)
total	The sum over the period
earnings_balance	What you can withdraw now
running_rentals_billed_before_fee	What rentals still running have billed so far, before the fee; they are added to days on the day they end

Example: never rented twice, and a heat alert

A small Python loop for a machine you also list elsewhere: it takes the node off ParalonCloud while your other marketplace has it, puts it back after, and warns when a GPU runs hot.

import os, time, requests

API = "https://paraloncloud.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['PARALON_API_KEY']}"}
NODE = os.environ["PARALON_NODE_ID"]

def rented_elsewhere() -> bool:
    ...  # ask your other marketplace whether this machine is rented there

while True:
    node = requests.get(f"{API}/nodes/{NODE}", headers=H, timeout=30).json()
    busy = rented_elsewhere()
    if busy and node["available"] and node["state"] != "rented":
        requests.patch(f"{API}/nodes/{NODE}", headers=H, json={"available": False}, timeout=30)
    elif not busy and not node["available"]:
        requests.patch(f"{API}/nodes/{NODE}", headers=H, json={"available": True}, timeout=30)
    for gpu in (node.get("metrics") or {}).get("gpus", []):
        if (gpu.get("temperature_c") or 0) >= 85:
            print(f"{node['name']}: GPU at {gpu['temperature_c']} °C")
    time.sleep(60)

Limits and errors

Requests count against the key's per-minute limit, shared with inference and rentals; adding nodes is also capped at 20 an hour per key.

Errors are JSON with error and message:

HTTP	error	When
400	invalid_request	A missing or wrong field, a price outside the range, an unknown field
401	invalid_api_key	No key, or the key is wrong or revoked
403	insufficient_scope	The key has no nodes scope
404	node_not_found	No such node on this account
409	conflict	Changing spot while rented, reclaiming a node that is not spot
429	rate_limit_exceeded	Too many requests this minute, or too many nodes added this hour