From 49a38c74ce205c4729e22f380d976a3754039180 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 13:31:05 -0700 Subject: [PATCH 01/45] First draft for SLA documentation --- host/hosting-overview.mdx | 1 + host/sla-backtester.mdx | 221 +++++++++++++++++++++++++++++ host/sla-offers.mdx | 167 ++++++++++++++++++++++ snippets/host/cli/list-machine.mdx | 12 ++ snippets/host/sdk/list-machine.mdx | 17 ++- 5 files changed, 417 insertions(+), 1 deletion(-) create mode 100644 host/sla-backtester.mdx create mode 100644 host/sla-offers.mdx diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 5589bdf8..84f89c32 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -47,6 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) - the offer end date, which determines how long the offer accepts new rental contracts +- optional [SLA (reliability guarantee)](/host/sla-offers) parameters — reliability target, claim, and confidence The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx new file mode 100644 index 00000000..916e136b --- /dev/null +++ b/host/sla-backtester.mdx @@ -0,0 +1,221 @@ +--- +title: "SLA Earnings Backtester" +description: "Replay your machine's historical earnings through SLA math to preview premiums and payouts before listing." +"canonical": "/host/sla-backtester" +--- + +The **SLA earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability **R** with confidence **P**, how would that have affected my earnings on this machine over the last few months?* + +It replays your machine's **real historical compute earnings and uptime** through the same v5 SLA math used in production settlement, then compares the simulated result to what you actually earned from SLA (if anything). + + +The backtester is available through the API only. You must own the machine and use an API key with **`machine_read`** permission. + + +## When to use it + +Use the backtester before you enable SLA on a listing, or when you want to tune parameters: + +- **Pick a reliability target** — see how often you would have kept premiums vs paid out +- **Compare confidence levels** — tighter confidence means higher premiums for clients but more risk to you if uptime slips +- **Stress-test bad weeks** — use the optional flat uptime override to see payout size if reliability dropped +- **Compare to history** — each day includes `historical_sla`, your machine's realized SLA earnings in that period (zero if you were not offering SLA) + +For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). + +## How it works + +1. You choose a machine, date range, reliability target (`r`), and confidence (`p`). +2. The API loads per-day earnings from your machine's history (`machine_earns`). +3. For each active day, it computes GPU, storage, and bandwidth earnings plus simulated SLA host earnings. +4. It returns a day-by-day breakdown and summary totals. + +**Simulated vs listing parameters.** In the backtester, reliability target and claim are both set to **`r`**. When you actually list a machine, you can set **`sla_r_claim` above `sla_r_target`** for lower client premiums. The backtester is conservative: it shows the economics when target and claim match. + +**Active vs idle days.** Days with no rental activity (zero compute delta) appear in the results as zero-filled rows but do not count toward `covered_days`. Only days with actual earnings are replayed through SLA math. + +## API reference + +``` +GET /api/v0/host/sla_backtest/ +``` + +Requires Bearer authentication. Rate limited like other host API endpoints. + +### Query parameters + +| Parameter | Required | Description | +| --- | --- | --- | +| `machine_id` | Yes | ID of your machine | +| `r` | Yes | Reliability target to simulate (0–1). Used as both target and claim. Example: `0.95` = 95%. | +| `p` | No | Host confidence (0–1). Maps to the same spread used when listing with `sla_sigma_x`. Default: ~0.67 (normal confidence). | +| `start_date` | No | Range start as Unix epoch seconds. Default: 90 days before `end_date`. | +| `end_date` | No | Range end as Unix epoch seconds. Default: now. | +| `reliability` | No | Optional flat uptime override (0–1) for all replayed days. Ignores historical uptime — useful for what-if analysis ("what if every day had 90% uptime?"). | + +### Limits + +| Limit | Value | +| --- | --- | +| Default lookback | 90 days | +| Maximum range | 366 days (inclusive) | +| Ownership | Must own the machine | + +### Example request + +```bash +curl -s -H "Authorization: Bearer YOUR_API_KEY" \ + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.95&p=0.67&start_date=1704067200&end_date=1711929600" +``` + +Compare two confidence levels on the same history: + +```bash +# Normal confidence (~67%) +curl -s -H "Authorization: Bearer YOUR_API_KEY" \ + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.67" + +# High confidence (~83%) — tighter spread, lower simulated premiums +curl -s -H "Authorization: Bearer YOUR_API_KEY" \ + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.83" +``` + +Stress-test with flat 90% uptime: + +```bash +curl -s -H "Authorization: Bearer YOUR_API_KEY" \ + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.67&reliability=0.90" +``` + +## Reading the response + +A successful response looks like this (fields abbreviated): + +```json +{ + "success": true, + "machine_id": 12345, + "has_data": true, + "start_day": 19723, + "end_day": 19812, + "covered_days": 45, + "skipped_days": 45, + "reliability": 0.998500, + "fleet_reliability": 0.991200, + "params": { + "r": 0.95, + "p": 0.6667, + "sigma_x": 0.5, + "reliability": null + }, + "daily_results": [ + { + "day": 19723, + "gpu": 84.0, + "storage": 2.4, + "bandwidth": 0.1, + "uptime": 1.0, + "sla": 0.18, + "historical_sla": 0.0 + } + ], + "summary": { + "total_gpu": 3780.0, + "total_storage": 108.0, + "total_bandwidth": 4.5, + "total_sla": 8.1, + "total_earnings": 3900.6, + "total_historical_sla": 0.0, + "worst_day_loss": 42.0 + } +} +``` + +### Top-level fields + +| Field | Meaning | +| --- | --- | +| `has_data` | `true` if at least one day in the range had earnings to replay | +| `covered_days` | Days with rental activity replayed through SLA math | +| `skipped_days` | Days in the range with no activity (zero-filled in `daily_results`) | +| `reliability` | Actual uptime ratio over the range (`total uptime / total active time`) | +| `fleet_reliability` | Average reliability across your other machines (context only) | + +### Per-day fields (`daily_results`) + +| Field | Meaning | +| --- | --- | +| `gpu`, `storage`, `bandwidth` | That day's compute earnings breakdown ($) | +| `uptime` | Uptime fraction for the day (0–1), or your flat override if set | +| `sla` | **Simulated SLA host earnings** for the day. Positive = you keep premium; negative = you pay the client | +| `historical_sla` | What you **actually** earned from SLA that day (signed). Zero if you were not offering SLA | + +Plot `sla` over time to see which days would have helped or hurt under the chosen parameters. Compare against `historical_sla` to see how simulated economics differ from reality. + +### Summary fields + +| Field | Meaning | +| --- | --- | +| `total_gpu`, `total_storage`, `total_bandwidth` | Compute earnings over covered days | +| `total_sla` | Net simulated SLA earnings. Positive = SLA would have added income overall | +| `total_earnings` | Compute + simulated SLA | +| `total_historical_sla` | Sum of realized historical SLA in the range | +| `worst_day_loss` | Largest single-day client payout (your worst simulated loss) | + +## Interpreting results + +### Mostly positive `sla` values + +Your historical uptime was strong relative to the target. SLA would likely have been a net positive — small premiums on good days, few payout days. + +### Negative `sla` on specific days + +Those days had uptime below your chosen target. The magnitude shows how much you would have paid out. If you see clusters of negative days, consider a lower target, wider confidence, or fixing reliability before listing SLA. + +### `total_sla` near zero + +Break-even territory — premiums and payouts roughly balance. Typical when your actual uptime matches your stated target. + +### `total_sla` strongly negative + +Under the simulated parameters, SLA would have cost you money over this window. Either improve uptime, lower the target, or widen confidence before listing. + +### Using `reliability` override + +Setting `reliability=0.90` while keeping `r=0.99` answers: *if every active day had 90% uptime, how bad would SLA payouts get?* Use this to understand tail risk before committing to a high target. + +## Confidence values (`p`) + +The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. They map to the same presets used when listing: + +| Confidence `p` | Approx. label | Listing equivalent | +| --- | --- | --- | +| `0.83` | High | `sla_sigma_x ≈ 0.2` | +| `0.67` | Normal (default) | `sla_sigma_x ≈ 0.5` | +| `0.50` | Wide | `sla_sigma_x ≈ 1.0` | + +Higher confidence (higher `p`) → tighter spread → lower premiums for clients, but less room for uptime to slip before payouts. + +## Error responses + +| HTTP | `error` | Cause | +| --- | --- | --- | +| 400 | `invalid_range` | `start_date` is after `end_date` | +| 400 | `range_too_large` | More than 366 days requested | +| 400 | `invalid_params` | Invalid `r`, `p`, or other SLA parameter | +| 403 | `not_owner` | Machine belongs to another host | +| 404 | `machine_not_found` | Invalid `machine_id` | + +## Recommended workflow + +1. **Run a baseline backtest** on a machine with at least a few weeks of rental history. Use your intended target and normal confidence (`p=0.67`). +2. **Check `worst_day_loss`** — can you absorb that payout from a bad day? +3. **Try a higher target** (for example `r=0.99`) and see how `total_sla` changes. +4. **Run a stress test** with `reliability=0.90` at your intended target. +5. **List with headroom** — set `sla_r_claim` above `sla_r_target` on the actual offer for better client pricing than the backtester shows (see [SLA Offers](/host/sla-offers)). + +## Related documentation + +- [SLA Offers](/host/sla-offers) — listing parameters, economics, and risk scenarios +- [SLA Coverage (clients)](/guides/instances/choosing/sla-coverage) — how clients search and pay for SLA +- [API permissions](/api-reference/permissions) — `machine_read` scope required diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx new file mode 100644 index 00000000..89090e27 --- /dev/null +++ b/host/sla-offers.mdx @@ -0,0 +1,167 @@ +--- +title: "SLA Offers" +description: "Offer reliability guarantees on your machines, set SLA parameters, and understand how premiums and payouts work." +"canonical": "/host/sla-offers" +--- + +Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is reliability insurance: the client pays a small daily premium, and if uptime falls short of the agreed target, the client receives a payout from your earnings. + +This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. + + +SLA settlement uses the **v5 asymmetric insurance model**. Premiums and payouts are settled daily based on measured uptime. + + +## How it works (plain English) + +Think of an SLA offer as three linked ideas: + +1. **Reliability target** — the uptime level the listing is priced around (for example, 95% or 99%). +2. **Your reliability claim** — what you believe your machine will actually deliver. +3. **Your confidence** — how sure you are about that claim. A tight confidence means you stand behind a narrow range; a wide confidence means you admit more uncertainty and clients pay a higher premium. + +When a client rents with SLA enabled: + +- They pay **compute** (GPU, storage, bandwidth) plus a **daily SLA premium**. +- Each day, Vast measures how long the instance was online and settles the SLA. +- **Good uptime** → you keep the premium for that day. +- **Bad uptime** → you pay the client from your earnings (up to the day's compute charges plus premium). + +Under honest pricing, a host who delivers what they claim should roughly break even on SLA over time — premiums balance payouts. + +## SLA parameters + +When you list or update a machine, you can set these fields on the offer (via the host console or the [list machine API](/api-reference/machines/list-machine)): + +| Parameter | API field | What it means | +| --- | --- | --- | +| Reliability target | `sla_r_target` | The coverage level baked into the offer. Set above `0` to enable SLA. Values are fractions between 0 and 1 (for example, `0.95` = 95%). Legacy alias: `sla_reliability`. | +| Reliability claim | `sla_r_claim` | Your advertised belief about machine uptime. Defaults to the reliability target if omitted. Must be **≥** the target. | +| Confidence spread | `sla_sigma_x` | How wide your belief is around the claim. Lower = more confident (cheaper for clients). Defaults to `0.5` if omitted. | + +### Confidence presets + +If you prefer thinking in confidence rather than `sla_sigma_x`, these presets match the shipped defaults: + +| Label | Approx. confidence | `sla_sigma_x` | Effect on premium | +| --- | --- | --- | --- | +| High | ~83% | `0.2` | Lowest premiums — you are very sure about your claim | +| Normal (default) | ~67% | `0.5` | Balanced default | +| Wide | 50% | `1.0` | Higher premiums — more uncertainty priced in | + +### Validation rules + +Offers with invalid combinations are rejected at listing time: + +- Reliability target and claim must be between 0 and 1 (exclusive of 0 for target). +- **Target cannot exceed claim** — you cannot promise coverage above what you claim you can deliver. +- Confidence spread must be positive and at most `3.0`. + +## Listing an SLA offer + +### Web console + +When listing a machine in the [host machines page](https://cloud.vast.ai/host/machines), enable SLA and set your reliability target, claim, and confidence. The console shows how these affect the premium clients will see. + +### CLI and API + +Pass SLA fields to `vastai list machine` or `PUT /api/v0/machines/create_asks/`: + +```bash +vastai list machine 12345 \ + --price_gpu 3.50 \ + --sla_r_target 0.95 \ + --sla_r_claim 0.99 \ + --sla_sigma_x 0.5 +``` + +Minimal example (claim and confidence use defaults): + +```json +{ + "machine": 12345, + "price_gpu": 3.50, + "sla_r_target": 0.95 +} +``` + +This creates an offer with target `0.95`, claim `0.95`, and confidence spread `0.5`. + + +Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. + + +## Economics walkthrough + +**Setup:** You list an H100 at **$3.50/hr** GPU price with target **95%**, claim **99%**, and normal confidence (`sla_sigma_x = 0.5`). + +| Item | Amount | +| --- | --- | +| Daily compute (`C`) | ~$84/day ($3.50 × 24 hr) | +| SLA premium to client | ~**$0.008/hr** (~$0.20/day) | + +This premium is what a client searching for 95% reliability would see added to `dph_total`. + +### If you meet your claim + +| Measured uptime (simplified) | Client net (per day) | You net (per day) | +| --- | --- | --- | +| ~100% (excellent day) | −$0.20 (paid premium) | +$0.20 (keep premium) | +| ~99% (good day) | −$0.17 | +$0.17 | + +You keep most or all of the premium. + +### If you miss the target + +Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: + +| Measured uptime (simplified) | Client net (per day) | You net (per day) | +| --- | --- | --- | +| At target (~95%) | ~+$42 | ~−$42 | +| Well below target (~90% or less) | ~+$84 (full compute refund) | ~−$84 | + +On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged twice for downtime they already did not pay for. + + +These examples use simplified single-day uptime for illustration. Production settlement aggregates uptime across multiple time windows (from about 1 day to about 3 years of history), so one bad hour does not always produce the maximum payout, and one good day does not instantly erase a long streak of problems. + + +## Risk scenarios + +### You claim 99% but deliver 99.5% + +You outperform your claim. Clients pay small premiums; payouts are rare. You net positive on SLA over time. + +### You claim 99% but have an offline day + +Clients receive payouts tied to how far measured uptime falls below the target. Extended outages can approach a full-day compute refund. Your reliability score and verification status may also be affected separately from SLA settlement. + +### You set target equal to claim (for example, both 95%) + +Premiums are **much higher** because you are not offering any headroom below your claim. Clients only buy this when they need coverage exactly at your stated level. Prefer setting **claim above target** (for example, claim 99%, target 95%) for competitive premiums. + +### You widen confidence (`sla_sigma_x` → 1.0) + +Clients pay more because you admit greater uncertainty. Use this if your uptime history is volatile or the machine is new. + +### Scheduled maintenance + +Maintenance windows that were scheduled with sufficient notice may be credited back toward uptime, reducing SLA penalties for planned downtime. Unplanned outages count fully. + +## Preview earnings before listing + +Use the [SLA Earnings Backtester](/host/sla-backtester) to replay your machine's historical earnings through SLA math and compare simulated premiums and payouts before you enable SLA on a listing. + +## Tips for competitive SLA offers + +- **Set claim above target.** A claim of 99% with a target of 95% produces a much lower premium than matching them both at 95%. +- **Tighten confidence only when earned.** Use high confidence (`sla_sigma_x ≈ 0.2`) after you have a strong uptime track record on that machine. +- **Keep the machine online during active contracts.** SLA payouts and verification are separate systems, but both respond to downtime. +- **Use the [SLA backtester](/host/sla-backtester)** to preview how different targets and confidence levels would have affected past earnings. + +## Related documentation + +- [SLA Earnings Backtester](/host/sla-backtester) — preview SLA economics on historical earnings +- [SLA Coverage for Clients](/guides/instances/choosing/sla-coverage) — how clients search, compare, and benefit from SLA offers +- [Hosting Overview](/host/hosting-overview) — offers, rental contracts, and listing basics +- [Understanding Verification](/host/understanding-verification) — platform verification (separate from SLA, but related to trust) diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 1c385fd7..4a066b81 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -60,6 +60,18 @@ vastai list machine ID [options] Price for disk on volume contract offer. Defaults to price_disk. Invalid if vol_size is 0. (alias: `--vol_price`) + + Client reliability coverage target (0–1). Values above 0 enable SLA on the offer. Legacy alias: `--sla_reliability`. (alias: `--sla-r-target`) + + + + Host reliability claim (0–1). Must be ≥ `sla_r_target`. Defaults to `sla_r_target` if omitted. (alias: `--sla-r-claim`) + + + + Host belief spread in log-failure space (0–3]. Lower = tighter confidence and lower client premiums. Defaults to `0.5`. (alias: `--sla-sigma-x`) + + ## Description Performs the same action as pressing the "LIST" button on the site https://cloud.vast.ai/host/machines. diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index a67e8bef..4ef27387 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -13,7 +13,10 @@ VastAI.list_machine( price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, - end_date: Optional[str] = None + end_date: Optional[str] = None, + sla_r_target: Optional[float] = None, + sla_r_claim: Optional[float] = None, + sla_sigma_x: Optional[float] = None, ) -> str ``` @@ -51,6 +54,18 @@ VastAI.list_machine( end_date + + Reliability coverage target (0–1). Values above 0 enable SLA. + + + + Host reliability claim (0–1). Must be ≥ sla_r_target. + + + + Host confidence spread (0–3]. Lower = tighter confidence. + + ## Returns `str`, Result from the API call. From f559418f10d1aaba197d4f7701c302b767c0631f Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 14:14:36 -0700 Subject: [PATCH 02/45] Address doc-review feedback for host SLA documentation. Register SLA pages in nav, align OpenAPI with listing/backtester endpoints, and fix clarity issues flagged across all-hosts review (confidence direction, broken links, jargon, onboarding gaps). Co-authored-by: Cursor --- api-reference/openapi.yaml | 165 ++++++++++++++++++- api-reference/openapi/yaml/list_machine.yaml | 24 ++- api-reference/openapi/yaml/sla_backtest.yaml | 149 +++++++++++++++++ api-reference/permissions.mdx | 1 + docs.json | 2 + host/hosting-overview.mdx | 6 +- host/sla-backtester.mdx | 25 ++- host/sla-offers.mdx | 26 +-- snippets/host/cli/list-machine.mdx | 4 +- snippets/host/sdk/list-machine.mdx | 15 +- 10 files changed, 387 insertions(+), 30 deletions(-) create mode 100644 api-reference/openapi/yaml/sla_backtest.yaml diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 5f36a511..fd677de1 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4499,7 +4499,8 @@ paths: description: 'Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform. - Allows setting pricing, minimum GPU requirements, end date and discount rates. + Allows setting pricing, minimum GPU requirements, end date, discount rates, + and SLA parameters. CLI Usage: `vastai list machine [options]`' @@ -4549,6 +4550,27 @@ paths: type: number format: float description: Maximum discount rate allowed for prepaid credits + sla_r_target: + type: number + format: float + description: "Client reliability coverage target (0\u20131). Values\ + \ above 0 enable SLA on the offer.\nLegacy alias: sla_reliability.\n" + sla_r_claim: + type: number + format: float + description: "Host reliability claim (0\u20131). Must be greater\ + \ than or equal to sla_r_target.\nDefaults to sla_r_target if\ + \ omitted.\n" + sla_sigma_x: + type: number + format: float + description: "Host confidence spread \u2014 how wide your belief\ + \ is around the claim.\nMust be greater than 0 and at most 3.0.\ + \ Defaults to 0.5.\n" + sla_reliability: + type: number + format: float + description: Legacy alias for sla_r_target. responses: '200': description: Successful response @@ -8989,6 +9011,147 @@ paths: tags: - Accounts operationId: showUser + /api/v0/host/sla_backtest: + get: + summary: sla backtest + description: 'Replays a machine''s historical compute earnings and uptime through + SLA settlement math + + to preview premiums and payouts before listing with SLA. + + + Requires `machine_read` permission. See [SLA Earnings Backtester](/host/sla-backtester) + for usage guide.' + security: + - BearerAuth: [] + parameters: + - name: machine_id + in: query + required: true + schema: + type: integer + description: ID of your machine. + - name: r + in: query + required: true + schema: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + maximum: 1 + description: "Reliability target to simulate (0\u20131). Used as both target\ + \ and claim." + - name: p + in: query + schema: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + maximum: 1 + default: 0.6667 + description: "Host confidence (0\u20131). Maps to sla_sigma_x when listing.\ + \ Default 0.6667 (normal)." + - name: start_date + in: query + schema: + type: integer + description: Range start as Unix epoch seconds. Default is 90 days before + end_date. + - name: end_date + in: query + schema: + type: integer + description: Range end as Unix epoch seconds. Default is now. + - name: reliability + in: query + schema: + type: number + format: float + minimum: 0 + maximum: 1 + description: "Optional flat uptime override (0\u20131) for all replayed days." + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + machine_id: + type: integer + has_data: + type: boolean + description: false when no days in the range had earnings to replay. + start_day: + type: integer + description: UTC day index (days since 1970-01-01). + end_day: + type: integer + description: UTC day index (days since 1970-01-01). + covered_days: + type: integer + skipped_days: + type: integer + reliability: + type: number + format: float + fleet_reliability: + type: number + format: float + params: + type: object + daily_results: + type: array + items: + type: object + summary: + type: object + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + error: + type: string + enum: + - invalid_range + - range_too_large + - bad_request + - invalid_params + msg: + type: string + '403': + description: "Forbidden \u2014 not machine owner" + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: not_owner + '404': + description: Machine not found + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: machine_not_found + '429': + description: "Too Many Requests \u2014 rate limit exceeded" + tags: + - Host + operationId: slaBacktest /api/v0/deployment/{id}/start: post: summary: start deployment diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index 9b35c946..5debd88f 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -12,7 +12,7 @@ paths: summary: list machine description: | Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform. - Allows setting pricing, minimum GPU requirements, end date and discount rates. + Allows setting pricing, minimum GPU requirements, end date, discount rates, and SLA parameters. CLI Usage: `vastai list machine [options]` security: @@ -61,6 +61,28 @@ paths: type: number format: float description: Maximum discount rate allowed for prepaid credits + sla_r_target: + type: number + format: float + description: | + Client reliability coverage target (0–1). Values above 0 enable SLA on the offer. + Legacy alias: sla_reliability. + sla_r_claim: + type: number + format: float + description: | + Host reliability claim (0–1). Must be greater than or equal to sla_r_target. + Defaults to sla_r_target if omitted. + sla_sigma_x: + type: number + format: float + description: | + Host confidence spread — how wide your belief is around the claim. + Must be greater than 0 and at most 3.0. Defaults to 0.5. + sla_reliability: + type: number + format: float + description: Legacy alias for sla_r_target. responses: '200': description: Successful response diff --git a/api-reference/openapi/yaml/sla_backtest.yaml b/api-reference/openapi/yaml/sla_backtest.yaml new file mode 100644 index 00000000..37a6e7a1 --- /dev/null +++ b/api-reference/openapi/yaml/sla_backtest.yaml @@ -0,0 +1,149 @@ +openapi: 3.0.0 +info: + title: Vast.ai API - SLA Backtest + description: Replay historical machine earnings through SLA settlement math. + version: 1.0.0 +servers: +- url: https://console.vast.ai + description: Production server +paths: + /api/v0/host/sla_backtest/: + get: + summary: sla backtest + description: | + Replays a machine's historical compute earnings and uptime through SLA settlement math + to preview premiums and payouts before listing with SLA. + + Requires `machine_read` permission. See [SLA Earnings Backtester](/host/sla-backtester) for usage guide. + security: + - BearerAuth: [] + parameters: + - name: machine_id + in: query + required: true + schema: + type: integer + description: ID of your machine. + - name: r + in: query + required: true + schema: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + maximum: 1 + description: Reliability target to simulate (0–1). Used as both target and claim. + - name: p + in: query + schema: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + maximum: 1 + default: 0.6667 + description: Host confidence (0–1). Maps to sla_sigma_x when listing. Default 0.6667 (normal). + - name: start_date + in: query + schema: + type: integer + description: Range start as Unix epoch seconds. Default is 90 days before end_date. + - name: end_date + in: query + schema: + type: integer + description: Range end as Unix epoch seconds. Default is now. + - name: reliability + in: query + schema: + type: number + format: float + minimum: 0 + maximum: 1 + description: Optional flat uptime override (0–1) for all replayed days. + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + machine_id: + type: integer + has_data: + type: boolean + description: false when no days in the range had earnings to replay. + start_day: + type: integer + description: UTC day index (days since 1970-01-01). + end_day: + type: integer + description: UTC day index (days since 1970-01-01). + covered_days: + type: integer + skipped_days: + type: integer + reliability: + type: number + format: float + fleet_reliability: + type: number + format: float + params: + type: object + daily_results: + type: array + items: + type: object + summary: + type: object + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + error: + type: string + enum: + - invalid_range + - range_too_large + - bad_request + - invalid_params + msg: + type: string + '403': + description: Forbidden — not machine owner + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: not_owner + '404': + description: Machine not found + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: machine_not_found + '429': + description: Too Many Requests — rate limit exceeded + tags: + - Host +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + description: Bearer authentication with API key in Authorization header diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx index b4a9b6c4..82cdd17a 100644 --- a/api-reference/permissions.mdx +++ b/api-reference/permissions.mdx @@ -194,6 +194,7 @@ Below is the complete mapping of which endpoints each permission category contro - [Show Machines](/api-reference/machines/show-machines) - [Show Reports](/api-reference/machines/show-reports) +- [SLA Backtest](/api-reference/host/sla-backtest) ### machine\_write diff --git a/docs.json b/docs.json index 62a07bf6..038a1157 100644 --- a/docs.json +++ b/docs.json @@ -599,6 +599,8 @@ "icon": "lightbulb", "pages": [ "host/hosting-overview", + "host/sla-offers", + "host/sla-backtester", "host/understanding-verification", "host/earning" ] diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 84f89c32..1f93a79b 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -125,7 +125,7 @@ The reserved discount pricing is determined by the hosts. If you intend to encou ![](/images/hosting-overview.webp) -Once that filter is selected, hosts who offer that discount will become easily visible. Hover over the rental button to see the discount rates that are offered. The original vs. the updated price will be shown as denoted by a stikethrough in the original amount: +Once that filter is selected, hosts who offer that discount will become easily visible. Hover over the rental button to see the discount rates that are offered. The original vs. the updated price will be shown as denoted by a strikethrough in the original amount: ![](/images/hosting-overview-2.webp) @@ -273,7 +273,7 @@ You can use the [uninstall script](https://s3.amazonaws.com/vast.ai/uninstall) ### What is this red error message on my machine? -If the hosting software detects and error, that error message will be listed on your machine in the machines page. Once the cause of the error has been resolved, most error messages will be automatically cleared after 1-2 hours. The quickest way to learn more about resolving specific error messages is to check out the hosting channels in [our discord](https://discord.gg/hSuEbSQ4X8). +If the hosting software detects an error, that error message will be listed on your machine in the machines page. Once the cause of the error has been resolved, most error messages will be automatically cleared after 1-2 hours. The quickest way to learn more about resolving specific error messages is to check out the hosting channels in [our discord](https://discord.gg/hSuEbSQ4X8). ### Why is my machine not listed? @@ -285,7 +285,7 @@ No, there is not an established process for hosts to message clients on Vast. ### I fear I will decrease my reliability from restarting my machine and potentially lose my verification. -Your machine's reliability does not directly affect your verification standing. Verification is independent of reliability. Though, whenever taking your machine offline and working on it you should procede with caution as it is easy to introduce new issues or errors that will cause your machine to be de-verified. +Your machine's reliability does not directly affect your verification standing. Verification is independent of reliability. Though, whenever taking your machine offline and working on it you should proceed with caution as it is easy to introduce new issues or errors that will cause your machine to be de-verified. ### How much can I make hosting on Vast? diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 916e136b..7713aee2 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -6,7 +6,7 @@ description: "Replay your machine's historical earnings through SLA math to prev The **SLA earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability **R** with confidence **P**, how would that have affected my earnings on this machine over the last few months?* -It replays your machine's **real historical compute earnings and uptime** through the same v5 SLA math used in production settlement, then compares the simulated result to what you actually earned from SLA (if anything). +It replays your machine's **real historical compute earnings and uptime** through the same SLA settlement math used in production, then compares the simulated result to what you actually earned from SLA (if anything). The backtester is available through the API only. You must own the machine and use an API key with **`machine_read`** permission. @@ -17,16 +17,16 @@ The backtester is available through the API only. You must own the machine and u Use the backtester before you enable SLA on a listing, or when you want to tune parameters: - **Pick a reliability target** — see how often you would have kept premiums vs paid out -- **Compare confidence levels** — tighter confidence means higher premiums for clients but more risk to you if uptime slips +- **Compare confidence levels** — tighter confidence means lower premiums for clients but more risk to you if uptime slips - **Stress-test bad weeks** — use the optional flat uptime override to see payout size if reliability dropped -- **Compare to history** — each day includes `historical_sla`, your machine's realized SLA earnings in that period (zero if you were not offering SLA) +- **Compare to history** — each day includes `historical_sla`, your machine's realized SLA earnings on that day (zero if you were not offering SLA) For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). ## How it works 1. You choose a machine, date range, reliability target (`r`), and confidence (`p`). -2. The API loads per-day earnings from your machine's history (`machine_earns`). +2. The API loads per-day earnings from your machine's rental history. 3. For each active day, it computes GPU, storage, and bandwidth earnings plus simulated SLA host earnings. 4. It returns a day-by-day breakdown and summary totals. @@ -40,7 +40,11 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). GET /api/v0/host/sla_backtest/ ``` -Requires Bearer authentication. Rate limited like other host API endpoints. +Requires Bearer authentication. This endpoint is rate-limited like other host API endpoints — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors) for retry guidance. + + +Find your API key under **Account → API Keys** (requires [`machine_read`](/api-reference/permissions) permission). Your machine ID appears on the [Host Machines page](https://cloud.vast.ai/host/machines) or via [`vastai show machines`](/host/cli/show-machines). + ### Query parameters @@ -48,7 +52,7 @@ Requires Bearer authentication. Rate limited like other host API endpoints. | --- | --- | --- | | `machine_id` | Yes | ID of your machine | | `r` | Yes | Reliability target to simulate (0–1). Used as both target and claim. Example: `0.95` = 95%. | -| `p` | No | Host confidence (0–1). Maps to the same spread used when listing with `sla_sigma_x`. Default: ~0.67 (normal confidence). | +| `p` | No | Host confidence (0–1). Maps to the same spread used when listing with `sla_sigma_x` — see [Confidence values](#confidence-values-p) below. Default: `0.6667` (normal confidence, ≈ 67%). | | `start_date` | No | Range start as Unix epoch seconds. Default: 90 days before `end_date`. | | `end_date` | No | Range end as Unix epoch seconds. Default: now. | | `reliability` | No | Optional flat uptime override (0–1) for all replayed days. Ignores historical uptime — useful for what-if analysis ("what if every day had 90% uptime?"). | @@ -60,6 +64,7 @@ Requires Bearer authentication. Rate limited like other host API endpoints. | Default lookback | 90 days | | Maximum range | 366 days (inclusive) | | Ownership | Must own the machine | +| Rate limits | Per-endpoint; see [Rate Limits and Errors](/api-reference/rate-limits-and-errors) | ### Example request @@ -135,7 +140,8 @@ A successful response looks like this (fields abbreviated): | Field | Meaning | | --- | --- | -| `has_data` | `true` if at least one day in the range had earnings to replay | +| `has_data` | `true` if at least one day in the range had earnings to replay. When `false`, `daily_results` is empty and summary totals are zero. | +| `start_day`, `end_day` | UTC day indices (days since January 1, 1970). Same encoding as `daily_results[].day`. Multiply by 86400 for a Unix timestamp. | | `covered_days` | Days with rental activity replayed through SLA math | | `skipped_days` | Days in the range with no activity (zero-filled in `daily_results`) | | `reliability` | Actual uptime ratio over the range (`total uptime / total active time`) | @@ -202,7 +208,8 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients | --- | --- | --- | | 400 | `invalid_range` | `start_date` is after `end_date` | | 400 | `range_too_large` | More than 366 days requested | -| 400 | `invalid_params` | Invalid `r`, `p`, or other SLA parameter | +| 400 | `bad_request` | Invalid or out-of-range `r`, `p`, or other query parameter | +| 400 | `invalid_params` | Valid parameters but SLA math could not run (for example, insufficient history) | | 403 | `not_owner` | Machine belongs to another host | | 404 | `machine_not_found` | Invalid `machine_id` | @@ -217,5 +224,5 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients ## Related documentation - [SLA Offers](/host/sla-offers) — listing parameters, economics, and risk scenarios -- [SLA Coverage (clients)](/guides/instances/choosing/sla-coverage) — how clients search and pay for SLA +- [SLA Backtest API](/api-reference/host/sla-backtest) — formal API reference for this endpoint - [API permissions](/api-reference/permissions) — `machine_read` scope required diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 89090e27..86a6c544 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -9,7 +9,7 @@ Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listi This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. -SLA settlement uses the **v5 asymmetric insurance model**. Premiums and payouts are settled daily based on measured uptime. +SLA settlement uses an **asymmetric insurance model**: when uptime is good you keep the premium, but when uptime is bad client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. ## How it works (plain English) @@ -31,7 +31,7 @@ Under honest pricing, a host who delivers what they claim should roughly break e ## SLA parameters -When you list or update a machine, you can set these fields on the offer (via the host console or the [list machine API](/api-reference/machines/list-machine)): +When you list or update a machine, you can set these fields on the offer (via the host console, the [list machine CLI](/host/cli/list-machine), or `PUT /api/v0/machines/create_asks/`): | Parameter | API field | What it means | | --- | --- | --- | @@ -47,14 +47,14 @@ If you prefer thinking in confidence rather than `sla_sigma_x`, these presets ma | --- | --- | --- | --- | | High | ~83% | `0.2` | Lowest premiums — you are very sure about your claim | | Normal (default) | ~67% | `0.5` | Balanced default | -| Wide | 50% | `1.0` | Higher premiums — more uncertainty priced in | +| Wide | ~50% | `1.0` | Higher premiums — more uncertainty priced in | ### Validation rules Offers with invalid combinations are rejected at listing time: -- Reliability target and claim must be between 0 and 1 (exclusive of 0 for target). -- **Target cannot exceed claim** — you cannot promise coverage above what you claim you can deliver. +- The reliability target must be greater than 0 and at most 1. +- The reliability claim must be between 0 and 1 and must be **≥** the target. - Confidence spread must be positive and at most `3.0`. ## Listing an SLA offer @@ -65,7 +65,7 @@ When listing a machine in the [host machines page](https://cloud.vast.ai/host/ma ### CLI and API -Pass SLA fields to `vastai list machine` or `PUT /api/v0/machines/create_asks/`: +Pass SLA fields to `vastai list machine` or `PUT /api/v0/machines/create_asks/` (this endpoint creates or updates the listing for your machine): ```bash vastai list machine 12345 \ @@ -75,7 +75,7 @@ vastai list machine 12345 \ --sla_sigma_x 0.5 ``` -Minimal example (claim and confidence use defaults): +Minimal example (claim and confidence use defaults). Body for `PUT /api/v0/machines/create_asks/`: ```json { @@ -88,7 +88,7 @@ Minimal example (claim and confidence use defaults): This creates an offer with target `0.95`, claim `0.95`, and confidence spread `0.5`. -Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. +Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. ## Economics walkthrough @@ -100,7 +100,7 @@ Partial updates are supported when editing an existing listing. If you change on | Daily compute (`C`) | ~$84/day ($3.50 × 24 hr) | | SLA premium to client | ~**$0.008/hr** (~$0.20/day) | -This premium is what a client searching for 95% reliability would see added to `dph_total`. +This premium is what a client searching for 95% reliability would see added to `dph_total` (dollars per hour, total rental price). ### If you meet your claim @@ -113,14 +113,14 @@ You keep most or all of the premium. ### If you miss the target -Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: +These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: | Measured uptime (simplified) | Client net (per day) | You net (per day) | | --- | --- | --- | | At target (~95%) | ~+$42 | ~−$42 | | Well below target (~90% or less) | ~+$84 (full compute refund) | ~−$84 | -On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged twice for downtime they already did not pay for. +On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged twice for downtime they already did not pay for. Your maximum SLA loss on a single day is capped at that day's compute revenue. These examples use simplified single-day uptime for illustration. Production settlement aggregates uptime across multiple time windows (from about 1 day to about 3 years of history), so one bad hour does not always produce the maximum payout, and one good day does not instantly erase a long streak of problems. @@ -146,7 +146,7 @@ Clients pay more because you admit greater uncertainty. Use this if your uptime ### Scheduled maintenance -Maintenance windows that were scheduled with sufficient notice may be credited back toward uptime, reducing SLA penalties for planned downtime. Unplanned outages count fully. +Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) with sufficient advance notice may be credited back toward uptime, reducing SLA penalties for planned downtime. Unplanned outages count fully. ## Preview earnings before listing @@ -157,11 +157,11 @@ Use the [SLA Earnings Backtester](/host/sla-backtester) to replay your machine's - **Set claim above target.** A claim of 99% with a target of 95% produces a much lower premium than matching them both at 95%. - **Tighten confidence only when earned.** Use high confidence (`sla_sigma_x ≈ 0.2`) after you have a strong uptime track record on that machine. - **Keep the machine online during active contracts.** SLA payouts and verification are separate systems, but both respond to downtime. +- **SLA applies to on-demand listings.** [Interruptible](/guides/instances/rental-types) instances use a separate bidding model and are not covered by SLA. - **Use the [SLA backtester](/host/sla-backtester)** to preview how different targets and confidence levels would have affected past earnings. ## Related documentation - [SLA Earnings Backtester](/host/sla-backtester) — preview SLA economics on historical earnings -- [SLA Coverage for Clients](/guides/instances/choosing/sla-coverage) — how clients search, compare, and benefit from SLA offers - [Hosting Overview](/host/hosting-overview) — offers, rental contracts, and listing basics - [Understanding Verification](/host/understanding-verification) — platform verification (separate from SLA, but related to trust) diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 4a066b81..8887e2f4 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -61,7 +61,7 @@ vastai list machine ID [options] - Client reliability coverage target (0–1). Values above 0 enable SLA on the offer. Legacy alias: `--sla_reliability`. (alias: `--sla-r-target`) + Client reliability coverage target (0–1). Values above 0 enable SLA on the offer. Set to `0` to disable SLA. Legacy alias: `--sla_reliability`. (alias: `--sla-r-target`) @@ -69,7 +69,7 @@ vastai list machine ID [options] - Host belief spread in log-failure space (0–3]. Lower = tighter confidence and lower client premiums. Defaults to `0.5`. (alias: `--sla-sigma-x`) + Host confidence spread — how wide your belief is around the claim. Must be greater than 0 and at most 3.0. Lower = tighter confidence and lower client premiums. Defaults to `0.5`. (alias: `--sla-sigma-x`) ## Description diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 4ef27387..12bf7112 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -63,7 +63,7 @@ VastAI.list_machine( - Host confidence spread (0–3]. Lower = tighter confidence. + Host confidence spread — how wide your belief is around the claim. Must be greater than 0 and at most 3.0. Lower = tighter confidence. ## Returns @@ -79,3 +79,16 @@ client = VastAI(api_key="YOUR_API_KEY") result = client.list_machine(id=12345) print(result) ``` + +With SLA enabled: + +```python +result = client.list_machine( + id=12345, + price_gpu=3.50, + sla_r_target=0.95, + sla_r_claim=0.99, + sla_sigma_x=0.5, +) +print(result) +``` From e32b1e7c693ffa94d84bcb8bf0dc1bfb06bba139 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:12:35 -0700 Subject: [PATCH 03/45] docs(sla): address doc-review consensus (cycle 1) Align create_asks error codes with production, add OpenAPI earnings fleet-scope note, choose-your-path routing, and merge duplicate FAQs. Co-authored-by: Cursor --- api-reference/openapi.yaml | 186 +++++++++-- api-reference/openapi/yaml/list_machine.yaml | 76 ++++- api-reference/openapi/yaml/show_earnings.yaml | 11 + api-reference/openapi/yaml/sla_backtest.yaml | 82 ++++- api-reference/permissions.mdx | 2 +- host/hosting-overview.mdx | 42 +-- host/sla-backtester.mdx | 140 ++++++-- host/sla-offers.mdx | 302 ++++++++++++++++-- snippets/host/cli/list-machine.mdx | 24 +- snippets/host/sdk/list-machine.mdx | 52 +-- 10 files changed, 740 insertions(+), 177 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index fd677de1..875b2e55 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4553,14 +4553,20 @@ paths: sla_r_target: type: number format: float - description: "Client reliability coverage target (0\u20131). Values\ - \ above 0 enable SLA on the offer.\nLegacy alias: sla_reliability.\n" + minimum: 0 + maximum: 0.9999 + description: "Client reliability coverage target. Values above 0 enable\ + \ SLA on the offer.\nMust be greater than 0 and at most 0.9999\ + \ when enabling SLA; exactly 1.0 is rejected.\nSet to 0 to disable\ + \ SLA. Legacy alias: sla_reliability.\n" sla_r_claim: type: number format: float - description: "Host reliability claim (0\u20131). Must be greater\ - \ than or equal to sla_r_target.\nDefaults to sla_r_target if\ - \ omitted.\n" + minimum: 0 + maximum: 0.9999 + description: "Host reliability claim. Must be greater than 0, at\ + \ most 0.9999, and greater than or equal to sla_r_target.\nDefaults\ + \ to sla_r_target if omitted.\n" sla_sigma_x: type: number format: float @@ -4581,15 +4587,42 @@ paths: properties: success: type: boolean - extended: - type: integer - description: Number of client contracts extended to new end date - msg: - type: string - description: Status message if success is false + you_sent: + type: object + description: Echo of the request body + results: + type: array + items: + type: object + properties: + machine_id: + type: integer + user_id: + type: integer + extended: + type: integer + description: Number of rental contracts extended + new_contracts: + type: array + items: + type: integer + description: IDs of newly created contracts + upd_contracts: + type: array + items: + type: integer + description: IDs of updated contracts example: success: true - extended: 2 + you_sent: + machine: 12345 + sla_r_target: 0.95 + results: + - machine_id: 12345 + user_id: 67890 + extended: 1 + new_contracts: [] + upd_contracts: [1] '400': description: Bad Request content: @@ -4599,10 +4632,25 @@ paths: properties: error: type: string - example: invalid_args + enum: + - invalid_args + - invalid_sla_params + example: invalid_sla_params + msg: + type: string + example: No such machine(s) for your account + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + error: + type: string msg: type: string - example: Invalid machine id or parameters + example: Missing or invalid API key '403': description: Forbidden content: @@ -4612,10 +4660,13 @@ paths: properties: error: type: string + enum: + - not_authorized + - machine_locked example: not_authorized msg: type: string - example: Only machine owner can create ask contracts + example: API key lacks machine_write permission tags: - Machines operationId: listMachine @@ -7760,11 +7811,12 @@ paths: /api/v0/users/{user_id}/machine-earnings: get: summary: show earnings - description: 'Retrieves the earnings history for a specified time range and - optionally per machine. + description: | + Retrieves the earnings history for a specified time range and optionally per machine. + **Fleet scope:** `per_day[]` (including `sla_earn`) is always fleet-wide for the authenticated host, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn` and `summary.total_sla`. - CLI Usage: `vastai show earnings [options]`' + CLI Usage: `vastai show earnings [options]` security: - BearerAuth: [] parameters: @@ -7813,6 +7865,9 @@ paths: type: number total_bwd: type: number + total_sla: + type: number + description: Net SLA earnings over the requested window. username: type: string email: @@ -7857,6 +7912,9 @@ paths: type: number bwd_earn: type: number + sla_earn: + type: number + description: Net SLA earnings for this machine over the window. per_day: type: array items: @@ -7872,6 +7930,9 @@ paths: type: number bwd_earn: type: number + sla_earn: + type: number + description: Net host SLA settlement for the UTC day. Positive when the host keeps premium income; negative when the host pays the client. '400': description: Bad Request - Invalid input syntax content: @@ -9014,6 +9075,7 @@ paths: /api/v0/host/sla_backtest: get: summary: sla backtest + operationId: slaBacktest description: 'Replays a machine''s historical compute earnings and uptime through SLA settlement math @@ -9039,9 +9101,9 @@ paths: format: float minimum: 0 exclusiveMinimum: true - maximum: 1 - description: "Reliability target to simulate (0\u20131). Used as both target\ - \ and claim." + maximum: 0.9999 + description: Reliability target to simulate (greater than 0 and at most 0.9999). + Used as both target and claim. Exactly 1.0 is rejected. - name: p in: query schema: @@ -9049,10 +9111,11 @@ paths: format: float minimum: 0 exclusiveMinimum: true + exclusiveMaximum: true maximum: 1 default: 0.6667 - description: "Host confidence (0\u20131). Maps to sla_sigma_x when listing.\ - \ Default 0.6667 (normal)." + description: Host confidence (greater than 0 and less than 1). Maps to sla_sigma_x + when listing. Default 0.6667 (normal). - name: start_date in: query schema: @@ -9070,8 +9133,18 @@ paths: type: number format: float minimum: 0 + exclusiveMinimum: true maximum: 1 - description: "Optional flat uptime override (0\u20131) for all replayed days." + description: Optional flat uptime override (greater than 0 and at most 1) for + all replayed days. Exactly 0 is rejected. + - name: beta + in: query + schema: + type: number + format: float + default: 0.5 + description: Backtest-only timescale weighting. Default 0.5 when omitted. Not + used in live settlement. Contact support before changing. responses: '200': description: Successful response @@ -9103,14 +9176,79 @@ paths: fleet_reliability: type: number format: float + description: Average reliability across your machines (including + this one). Context only. params: type: object + properties: + r: + type: number + format: float + p: + type: number + format: float + sigma_x: + type: number + format: float + reliability: + type: number + format: float + nullable: true + beta: + type: number + format: float daily_results: type: array items: type: object + properties: + day: + type: integer + gpu: + type: number + format: float + storage: + type: number + format: float + bandwidth: + type: number + format: float + uptime: + type: number + format: float + sla: + type: number + format: float + historical_sla: + type: number + format: float summary: type: object + properties: + total_gpu: + type: number + format: float + total_storage: + type: number + format: float + total_bandwidth: + type: number + format: float + total_sla: + type: number + format: float + total_earnings: + type: number + format: float + total_historical_sla: + type: number + format: float + worst_day_loss: + type: number + format: float + reserve: + type: number + format: float '400': description: Bad Request content: diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index 5debd88f..b5ab49ed 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -64,14 +64,19 @@ paths: sla_r_target: type: number format: float + minimum: 0 + maximum: 0.9999 description: | - Client reliability coverage target (0–1). Values above 0 enable SLA on the offer. - Legacy alias: sla_reliability. + Client reliability coverage target. Values above 0 enable SLA on the offer. + Must be greater than 0 and at most 0.9999 when enabling SLA; exactly 1.0 is rejected. + Set to 0 to disable SLA. Legacy alias: sla_reliability. sla_r_claim: type: number format: float + minimum: 0 + maximum: 0.9999 description: | - Host reliability claim (0–1). Must be greater than or equal to sla_r_target. + Host reliability claim. Must be greater than 0, at most 0.9999, and greater than or equal to sla_r_target. Defaults to sla_r_target if omitted. sla_sigma_x: type: number @@ -93,15 +98,42 @@ paths: properties: success: type: boolean - extended: - type: integer - description: Number of client contracts extended to new end date - msg: - type: string - description: Status message if success is false + you_sent: + type: object + description: Echo of the request body + results: + type: array + items: + type: object + properties: + machine_id: + type: integer + user_id: + type: integer + extended: + type: integer + description: Number of rental contracts extended + new_contracts: + type: array + items: + type: integer + description: IDs of newly created contracts + upd_contracts: + type: array + items: + type: integer + description: IDs of updated contracts example: success: true - extended: 2 + you_sent: + machine: 12345 + sla_r_target: 0.95 + results: + - machine_id: 12345 + user_id: 67890 + extended: 1 + new_contracts: [] + upd_contracts: [1] '400': description: Bad Request content: @@ -111,10 +143,25 @@ paths: properties: error: type: string - example: invalid_args + enum: + - invalid_args + - invalid_sla_params + example: invalid_sla_params + msg: + type: string + example: No such machine(s) for your account + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + error: + type: string msg: type: string - example: Invalid machine id or parameters + example: Missing or invalid API key '403': description: Forbidden content: @@ -124,10 +171,13 @@ paths: properties: error: type: string + enum: + - not_authorized + - machine_locked example: not_authorized msg: type: string - example: Only machine owner can create ask contracts + example: API key lacks machine_write permission tags: - Machines components: diff --git a/api-reference/openapi/yaml/show_earnings.yaml b/api-reference/openapi/yaml/show_earnings.yaml index 97183ba3..62580d78 100644 --- a/api-reference/openapi/yaml/show_earnings.yaml +++ b/api-reference/openapi/yaml/show_earnings.yaml @@ -14,6 +14,8 @@ paths: description: | Retrieves the earnings history for a specified time range and optionally per machine. + **Note:** `per_day[]` aggregates SLA earnings across your entire fleet for each UTC day, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn` or `summary.total_sla`. + CLI Usage: `vastai show earnings [options]` security: - BearerAuth: [] @@ -63,6 +65,9 @@ paths: type: number total_bwd: type: number + total_sla: + type: number + description: Net SLA earnings over the requested window. username: type: string email: @@ -107,6 +112,9 @@ paths: type: number bwd_earn: type: number + sla_earn: + type: number + description: Net SLA earnings for this machine over the window. per_day: type: array items: @@ -122,6 +130,9 @@ paths: type: number bwd_earn: type: number + sla_earn: + type: number + description: Net host SLA settlement for the UTC day. Positive when the host keeps premium income; negative when the host pays the client. '400': description: Bad Request - Invalid input syntax content: diff --git a/api-reference/openapi/yaml/sla_backtest.yaml b/api-reference/openapi/yaml/sla_backtest.yaml index 37a6e7a1..f782b825 100644 --- a/api-reference/openapi/yaml/sla_backtest.yaml +++ b/api-reference/openapi/yaml/sla_backtest.yaml @@ -10,6 +10,7 @@ paths: /api/v0/host/sla_backtest/: get: summary: sla backtest + operationId: slaBacktest description: | Replays a machine's historical compute earnings and uptime through SLA settlement math to preview premiums and payouts before listing with SLA. @@ -32,8 +33,8 @@ paths: format: float minimum: 0 exclusiveMinimum: true - maximum: 1 - description: Reliability target to simulate (0–1). Used as both target and claim. + maximum: 0.9999 + description: Reliability target to simulate (greater than 0 and at most 0.9999). Used as both target and claim. Exactly 1.0 is rejected. - name: p in: query schema: @@ -41,9 +42,10 @@ paths: format: float minimum: 0 exclusiveMinimum: true + exclusiveMaximum: true maximum: 1 default: 0.6667 - description: Host confidence (0–1). Maps to sla_sigma_x when listing. Default 0.6667 (normal). + description: Host confidence (greater than 0 and less than 1). Maps to sla_sigma_x when listing. Default 0.6667 (normal). - name: start_date in: query schema: @@ -60,8 +62,16 @@ paths: type: number format: float minimum: 0 + exclusiveMinimum: true maximum: 1 - description: Optional flat uptime override (0–1) for all replayed days. + description: Optional flat uptime override (greater than 0 and at most 1) for all replayed days. Exactly 0 is rejected. + - name: beta + in: query + schema: + type: number + format: float + default: 0.5 + description: Backtest-only timescale weighting. Default 0.5 when omitted. Not used in live settlement. Contact support before changing. responses: '200': description: Successful response @@ -93,14 +103,78 @@ paths: fleet_reliability: type: number format: float + description: Average reliability across your machines (including this one). Context only. params: type: object + properties: + r: + type: number + format: float + p: + type: number + format: float + sigma_x: + type: number + format: float + reliability: + type: number + format: float + nullable: true + beta: + type: number + format: float daily_results: type: array items: type: object + properties: + day: + type: integer + gpu: + type: number + format: float + storage: + type: number + format: float + bandwidth: + type: number + format: float + uptime: + type: number + format: float + sla: + type: number + format: float + historical_sla: + type: number + format: float summary: type: object + properties: + total_gpu: + type: number + format: float + total_storage: + type: number + format: float + total_bandwidth: + type: number + format: float + total_sla: + type: number + format: float + total_earnings: + type: number + format: float + total_historical_sla: + type: number + format: float + worst_day_loss: + type: number + format: float + reserve: + type: number + format: float '400': description: Bad Request content: diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx index 82cdd17a..cb08e0b6 100644 --- a/api-reference/permissions.mdx +++ b/api-reference/permissions.mdx @@ -194,7 +194,7 @@ Below is the complete mapping of which endpoints each permission category contro - [Show Machines](/api-reference/machines/show-machines) - [Show Reports](/api-reference/machines/show-reports) -- [SLA Backtest](/api-reference/host/sla-backtest) +- [SLA Backtest](/api-reference/host/sla-backtest) — API-only (hosts): replay historical earnings through SLA math. Requires `machine_read`. See [SLA Backtester](/host/sla-backtester). Console hosts should use **Set Pricing → SLA** preview instead. ### machine\_write diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 1f93a79b..27a08dc0 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -38,16 +38,16 @@ Clients have high expectations coming from AWS or GCP. As a host, plan to offer ## Offers and Rental Contracts -Hosts can create offers (sometimes called listings) through the CLI command list machine or the machine control panel GUI on the host machines page. +Hosts can create offers (sometimes called listings) through the CLI command `list machine` or the GUI on the [host machines page](https://cloud.vast.ai/host/machines). The main offer parameters include: -- the pricing for GPUs,internet,storage +- the pricing for GPUs, internet, storage - the discount schedule param which determines the price difference between [on-demand](/guides/instances/rental-types) and [reserved](/guides/instances/rental-types) instances - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) - the offer end date, which determines how long the offer accepts new rental contracts -- optional [SLA (reliability guarantee)](/host/sla-offers) parameters — reliability target, claim, and confidence +- **SLA (optional):** A reliability guarantee that clients can pay a premium for. Configure via **Set Pricing → SLA** in the console or the REST API — SLA parameters are not yet available in the published CLI/SDK. See [SLA Offers](/host/sla-offers) for parameters and field names. The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. @@ -59,7 +59,7 @@ Once clients rent your machine, it is very important to honor the terms of each ## The Rental Contract -By listing your machine, you create an offer visible to potential clients. A rental contract is created each time a client accepts your offer by renting an instance. The rental contract locks in all of the offer's terms at the time of rental, including pricing, the rental end date, and hardware specs, and those terms cannot be changed afterward. Each rental contract is independent, you may have multiple active rental contracts from different clients on the same machine, each with its own rental end date and pricing. +By listing your machine, you create an offer visible to potential clients. A rental contract is created each time a client accepts your offer by renting an instance. The rental contract locks in all of the offer's terms at the time of rental, including pricing, the rental end date, and hardware specs, and those terms cannot be changed afterward. Each rental contract is independent. You may have multiple active rental contracts from different clients on the same machine, each with its own rental end date and pricing. SLA terms lock at rent time — see [SLA on extended contracts](/host/sla-offers#sla-on-extended-contracts). As the host, you are _committing_ to provide the services as advertised in your offer: @@ -107,7 +107,7 @@ You now have two active rental contracts on the same machine at different prices ### Min GPU -When clicking on the set pricing button, there is a min GPU field. The min GPU field allows you to set the smallest grouping of GPU rentals available on your machine in powers of 2, or down to 1. For example, if you have an 8X 3090 and set min gpu to 2, clients can create instances with 2, 4, or 8 GPUs. If you set min gpus to 1, then clients can make instances with 1, 2, 4 or 8 GPUs. +When clicking on the set pricing button, there is a min GPU field. The min GPU field allows you to set the smallest grouping of GPU rentals available on your machine in powers of 2, or down to 1. For example, if you have an 8X 3090 and set min GPU to 2, clients can create instances with 2, 4, or 8 GPUs. If you set min GPU to 1, then clients can make instances with 1, 2, 4 or 8 GPUs. ### On-demand Price @@ -129,7 +129,7 @@ Once that filter is selected, hosts who offer that discount will become easily v ![](/images/hosting-overview-2.webp) -This discount is not static, but rather scales over time that the user rents the machine for. These values are determined by the individual host(s). +This discount is not static, but rather scales with the length of time the user rents the machine. These values are determined by individual hosts. As a host, you can set this number yourself to 0 if you wish to opt out of this feature. @@ -195,7 +195,7 @@ If you have raised the pricing, you cannot extend the current rental contracts. ## Testing your own machine -It is vital to test your own machine to ensure the ports and software is running smoothly. +It is vital to test your own machine to ensure the ports and software are running smoothly. ### Setup a separate client account @@ -235,7 +235,9 @@ Unlisting the offer will prevent new rental contracts from being created, but do Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored, you cannot take the machine offline until every active rental contract has ended. -For unplanned or unscheduled maintenance, use the CLI and the schedule maint command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. +For unplanned or unscheduled maintenance, use the CLI and the [`vastai schedule maint`](/host/cli/schedule-maint) command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. + +For SLA-listed machines, scheduled downtime may still count against your reliability target. Uptime credit for maintenance is evaluated case by case and is not guaranteed — give at least 24 hours' notice before extended work. When you schedule maintenance, clients may be notified via [Host Notifications](/host/notifications) (including `maintenance_scheduled` webhooks). See [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). ## Uninstalling @@ -251,17 +253,23 @@ Hosting on Vast will require some Linux knowledge, as you will be maintaining a You can create an invoice by going to the "Billing" page, and then click the box for "Include Charges" under "Generate Billing History". -### How do I check if my machine is listed? +### Why can't I find my machine in search? + +If your machine seems unlisted or missing from console search: -If your machine seems unlisted, try this command `vastai search offers 'machine_id=MACHINE_ID verified=any'` to see if the CLI finds it. If there is a result, your machine is properly listed +- **CLI check:** `vastai search offers 'machine_id=MACHINE_ID verified=any'` — if this returns a result, your machine is listed. +- **Console search:** There are 10,000+ listings; search shows a small subset. You usually cannot find one specific machine through normal browsing — this is expected. +- **Ranking check:** Use narrow filters to see similar machines, e.g. `vastai search offers 'gpu_name=RTX_4090 cpu_ram>257 cpu_ram<258'`. + +See also [Why is my machine not listed?](#why-is-my-machine-not-listed) below. ### Can you verify my machine? -Verification is conducted in a randomized and automated fashion. We only run manual verification tests are for datacenters and high end machines. +Verification is conducted in a randomized and automated fashion. We only run manual verification tests for datacenters and high-end machines. ### How does verification work? -Verification is mostly for higher end machines, mining rigs may never be verified. Verification is also based on supply vs demand and is machine/gpu specific. Right now the only machines which can expect fast verification are \$10k+: H100 or A100 80GB - if not tested quickly in a day or so let us know. 8x4090, 4xA6000 - should be tested in less than a week, especially if you have a number of them The only manual verification tests are for datacenters and high end machines. For everything else we run more random auto verification roughly about once a week. For datacenter partner inquiries email us at [contact@vast.ai](mailto:contact@vast.ai) directly. +Verification is mostly for higher end machines, mining rigs may never be verified. Verification is also based on supply vs demand and is machine/GPU specific. Right now the only machines which can expect fast verification are \$10k+: H100 or A100 80GB - if not tested quickly in a day or so let us know. 8x4090, 4xA6000 - should be tested in less than a week, especially if you have a number of them. The only manual verification tests are for datacenters and high-end machines. For everything else we run more random auto verification roughly about once a week. For datacenter partner inquiries email us at [contact@vast.ai](mailto:contact@vast.ai) directly. ### How do I gain datacenter status? @@ -277,7 +285,7 @@ If the hosting software detects an error, that error message will be listed on y ### Why is my machine not listed? -You won't be able to see it on the GUI right away, but you can search using the [CLI](/guides/instances/managing-instances). +You won't be able to see it on the GUI right away, but you can search using the [CLI](/guides/instances/managing-instances). See [Why can't I find my machine in search?](#why-cant-i-find-my-machine-in-search) above for the full checklist. ### Can I send a message to a client using my machine letting them know that I fixed an issue that they were having? @@ -306,11 +314,3 @@ Prior images are cached. ### My storage for clients is somehow full. I just have a few jobs stored in my server and most of them are old and didn't delete once the job finished. A lot of them are really old, can I remove them to free up some space? We suggest that you try cleaning up the docker build cache, as it sometimes frees up far more space than it claims. You can also clean up old unused images. - -### I can't find my machine? - -If your machine seems unlisted, try this command `vastai search offers 'machine_id=MACHINE_ID verified=any'` to see if the CLI finds it. If there is a result, your machine is properly listed. - -### Why can't I see my machine on the Search page in the console? - -There are over 10,000+ listings on Vast, and search only displays a small subset. You will usually not be able to find any one specific machine through most normal searches. This is expected and intentional behavior of our system. You can use `vastai search offers 'machine_id=MACHINE_ID verified=any'`, to see your machine's listing. If you want to get an understanding of the machines ranking above yours you can use very narrow filters to see what similar machines are ranking above you. For example, something like: `vastai search offers 'gpu_name=RTX_4090 cpu_ram>257 cpu_ram<258'` is a decently constrained search that will most likely include a given machine you are looking for (that fits these filters) amongst others that are similar. Keep in mind our Auto Sort that `search offers` defaults to is comprised of both ranking various factors as well as an element of randomness. \ No newline at end of file diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 7713aee2..1dfeb644 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -4,19 +4,27 @@ description: "Replay your machine's historical earnings through SLA math to prev "canonical": "/host/sla-backtester" --- -The **SLA earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability **R** with confidence **P**, how would that have affected my earnings on this machine over the last few months?* +The **SLA earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability target **`r`** and confidence level **`p`**, how would that have affected my earnings on this machine over the last few months?* (**`r`** = reliability target; **`p`** = host confidence — both defined in [Query parameters](#query-parameters) below.) It replays your machine's **real historical compute earnings and uptime** through the same SLA settlement math used in production, then compares the simulated result to what you actually earned from SLA (if anything). -The backtester is available through the API only. You must own the machine and use an API key with **`machine_read`** permission. +**Don't want to use the API?** The backtester is optional. Use the web console SLA preview and the economics walkthrough on [SLA Offers](/host/sla-offers#listing-an-sla-offer) to evaluate SLA before listing. The backtester is for hosts who want historical replay via the API. +## Choose your path + +| If you want to… | Use | +| --- | --- | +| Preview SLA before your first listing | Web console (**Set Pricing → SLA** on the machine page) — no API key needed | +| Simulate historical earnings for one machine | This page's single-machine `curl` example | +| Review many machines at once | [Fleet workflow](#fleet-workflow) below (advanced; Linux/macOS + `jq`) | + ## When to use it -Use the backtester before you enable SLA on a listing, or when you want to tune parameters: +Use the backtester before you enable SLA on a listing, or when you want to tune parameters. The machine needs at least a few weeks of rental history. If `has_data` is `false`, widen the date range or pick a machine with more activity: -- **Pick a reliability target** — see how often you would have kept premiums vs paid out +- **Pick a reliability target** — see how often you would have kept premiums or paid them out on historical data - **Compare confidence levels** — tighter confidence means lower premiums for clients but more risk to you if uptime slips - **Stress-test bad weeks** — use the optional flat uptime override to see payout size if reliability dropped - **Compare to history** — each day includes `historical_sla`, your machine's realized SLA earnings on that day (zero if you were not offering SLA) @@ -30,12 +38,33 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). 3. For each active day, it computes GPU, storage, and bandwidth earnings plus simulated SLA host earnings. 4. It returns a day-by-day breakdown and summary totals. -**Simulated vs listing parameters.** In the backtester, reliability target and claim are both set to **`r`**. When you actually list a machine, you can set **`sla_r_claim` above `sla_r_target`** for lower client premiums. The backtester is conservative: it shows the economics when target and claim match. +**Simulated vs listing parameters.** In the backtester, reliability target and claim are both set to **`r`**. When you actually list a machine, you can set **`sla_r_claim` above `sla_r_target`** for lower client premiums. + +**Active vs idle days.** **Idle days** are days with no rental earnings on the machine (no active compute rental). These days typically produce no SLA premium or payout in the simulation. Days with no rental activity appear in the results as zero-filled rows but do not count toward `covered_days`. Only days with actual earnings are replayed through SLA math. + + +**Simulation vs live listing** +- The backtester sets claim equal to target and may show higher premiums than live listing or the console preview. +- For client-visible pricing (`dph_total`), use **Set Pricing → SLA** in the console. +- For tail risk, trust `worst_day_loss`, not headline `total_sla`. +- The backtester defaults `beta` to `0.5` when omitted. Live SLA settlement does **not** use this default — weighting is fixed when you list. Treat `total_sla` as a tail-risk estimate, not an exact live preview. + + +## Before you start -**Active vs idle days.** Days with no rental activity (zero compute delta) appear in the results as zero-filled rows but do not count toward `covered_days`. Only days with actual earnings are replayed through SLA math. +**Prerequisites:** API key with `machine_read` permission, machine ID from the [Host Machines page](https://cloud.vast.ai/host/machines), and `curl` (or Postman). On Windows, use WSL or Postman. This is the same numeric machine ID as `machid` on the earnings API and `machine` in listing requests. + +1. Open **Account → API Keys** in the console and create a key with **`machine_read`** enabled. +2. Copy the token and use `Authorization: Bearer YOUR_API_KEY` in the examples below. See [Create API Key](/api-reference/accounts/create-api-key) and [Authentication](/api-reference/authentication). +3. Find your machine ID on the [Host Machines page](https://cloud.vast.ai/host/machines). The machine must have at least a few weeks of rental activity — new or idle machines should use the console **Set Pricing → SLA** preview instead (the backtester returns `has_data: false` without sufficient history). +4. Run the baseline `curl` below (default date range — no custom dates required) and check `has_data` in the response. ## API reference + +The backtester is available through the REST API only. You must own the machine and use an API key with **`machine_read`** permission. Python SDK (`vastai` package) support is not yet available — use the `curl` examples below. + + ``` GET /api/v0/host/sla_backtest/ ``` @@ -43,7 +72,7 @@ GET /api/v0/host/sla_backtest/ Requires Bearer authentication. This endpoint is rate-limited like other host API endpoints — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors) for retry guidance. -Find your API key under **Account → API Keys** (requires [`machine_read`](/api-reference/permissions) permission). Your machine ID appears on the [Host Machines page](https://cloud.vast.ai/host/machines) or via [`vastai show machines`](/host/cli/show-machines). +Find your API key under **Account → API Keys** (requires [`machine_read`](/api-reference/permissions) permission). See [Create API Key](/api-reference/accounts/create-api-key) if you need a new key. Your machine ID appears on the [Host Machines page](https://cloud.vast.ai/host/machines) or via [`vastai show machines`](/host/cli/show-machines). ### Query parameters @@ -51,11 +80,12 @@ Find your API key under **Account → API Keys** (requires [`machine_read`](/api | Parameter | Required | Description | | --- | --- | --- | | `machine_id` | Yes | ID of your machine | -| `r` | Yes | Reliability target to simulate (0–1). Used as both target and claim. Example: `0.95` = 95%. | -| `p` | No | Host confidence (0–1). Maps to the same spread used when listing with `sla_sigma_x` — see [Confidence values](#confidence-values-p) below. Default: `0.6667` (normal confidence, ≈ 67%). | +| `r` | Yes | Reliability target to simulate (greater than 0 and at most **0.9999**). Used as both target and claim. Example: `0.95` = 95%. Exactly `1.0` is rejected. | +| `p` | No | Host confidence (greater than 0 and **less than 1** — not equal to 1). Maps to the same spread used when listing with `sla_sigma_x` — see [Confidence values](#confidence-values-p) below. Default: `0.6667` (normal confidence, ≈ 67%). | | `start_date` | No | Range start as Unix epoch seconds. Default: 90 days before `end_date`. | | `end_date` | No | Range end as Unix epoch seconds. Default: now. | -| `reliability` | No | Optional flat uptime override (0–1) for all replayed days. Ignores historical uptime — useful for what-if analysis ("what if every day had 90% uptime?"). | +| `reliability` | No | Optional flat uptime override (greater than 0 and at most 1). Ignores historical uptime — useful for what-if analysis. Use `0.01` to approximate near-total downtime; `0` is rejected with `400 bad_request`. | +| `beta` | No | Backtest-only timescale weighting. Default `0.5` when omitted. **Not used in live settlement.** Contact support before changing. | ### Limits @@ -68,17 +98,29 @@ Find your API key under **Account → API Keys** (requires [`machine_read`](/api ### Example request +Minimal baseline (default 90-day lookback — no custom dates required): + +```bash +curl -s -H "Authorization: Bearer YOUR_API_KEY" \ + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.95&p=0.6667" +``` + +Custom date range (optional — Jan–Apr 2024 for illustration): + ```bash +# start_date = Jan 1, 2024; end_date = Apr 1, 2024 +# Tip: on Linux, `date -d '2024-01-01' +%s`; on macOS, `date -j -f '%Y-%m-%d' '2024-01-01' +%s` +# On Windows, use WSL or an online epoch converter. curl -s -H "Authorization: Bearer YOUR_API_KEY" \ - "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.95&p=0.67&start_date=1704067200&end_date=1711929600" + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.95&p=0.6667&start_date=1704067200&end_date=1711929600" ``` Compare two confidence levels on the same history: ```bash -# Normal confidence (~67%) +# Normal confidence (~67%, default 0.6667) curl -s -H "Authorization: Bearer YOUR_API_KEY" \ - "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.67" + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.6667" # High confidence (~83%) — tighter spread, lower simulated premiums curl -s -H "Authorization: Bearer YOUR_API_KEY" \ @@ -89,11 +131,13 @@ Stress-test with flat 90% uptime: ```bash curl -s -H "Authorization: Bearer YOUR_API_KEY" \ - "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.67&reliability=0.90" + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.6667&reliability=0.90" ``` ## Reading the response +**If you only read three fields:** Check `has_data` (widen dates if `false`), then `summary.worst_day_loss`, then `summary.total_sla`. + A successful response looks like this (fields abbreviated): ```json @@ -111,7 +155,8 @@ A successful response looks like this (fields abbreviated): "r": 0.95, "p": 0.6667, "sigma_x": 0.5, - "reliability": null + "reliability": null, + "beta": 0.5 }, "daily_results": [ { @@ -131,7 +176,8 @@ A successful response looks like this (fields abbreviated): "total_sla": 8.1, "total_earnings": 3900.6, "total_historical_sla": 0.0, - "worst_day_loss": 42.0 + "worst_day_loss": 42.0, + "reserve": 0.0 } } ``` @@ -140,12 +186,12 @@ A successful response looks like this (fields abbreviated): | Field | Meaning | | --- | --- | -| `has_data` | `true` if at least one day in the range had earnings to replay. When `false`, `daily_results` is empty and summary totals are zero. | -| `start_day`, `end_day` | UTC day indices (days since January 1, 1970). Same encoding as `daily_results[].day`. Multiply by 86400 for a Unix timestamp. | +| `has_data` | `true` if at least one day in the range had earnings to replay. When `false`, there was no billable rental activity in the range: `covered_days` is `0`, `skipped_days` equals the number of days in the requested window, `daily_results` contains one zero-filled row per day in the window (not an empty array), summary totals are `0.0`, and top-level `reliability` is `null`. Try a wider window or a machine with more rental history. | +| `start_day`, `end_day` | UTC day indices (days since January 1, 1970). Same encoding as `daily_results[].day`. Multiply by 86400 for a Unix timestamp. For example, day `19723` × 86400 = `1704067200` = January 1, 2024 UTC. Most hosts can ignore these and use `start_date`/`end_date` in requests. | | `covered_days` | Days with rental activity replayed through SLA math | | `skipped_days` | Days in the range with no activity (zero-filled in `daily_results`) | | `reliability` | Actual uptime ratio over the range (`total uptime / total active time`) | -| `fleet_reliability` | Average reliability across your other machines (context only) | +| `fleet_reliability` | Average reliability across your machines (including this one). Context only; may be uninformative if you operate a single machine. | ### Per-day fields (`daily_results`) @@ -167,12 +213,13 @@ Plot `sla` over time to see which days would have helped or hurt under the chose | `total_earnings` | Compute + simulated SLA | | `total_historical_sla` | Sum of realized historical SLA in the range | | `worst_day_loss` | Largest single-day client payout (your worst simulated loss) | +| `reserve` | Reserved for future use — ignore in production decisions today. | ## Interpreting results ### Mostly positive `sla` values -Your historical uptime was strong relative to the target. SLA would likely have been a net positive — small premiums on good days, few payout days. +Your historical uptime was strong relative to the target. SLA would likely have been a net positive — small premiums on good days, few days with payouts. ### Negative `sla` on specific days @@ -188,16 +235,20 @@ Under the simulated parameters, SLA would have cost you money over this window. ### Using `reliability` override -Setting `reliability=0.90` while keeping `r=0.99` answers: *if every active day had 90% uptime, how bad would SLA payouts get?* Use this to understand tail risk before committing to a high target. +Setting `reliability=0.90` while keeping `r=0.99` answers: *if every active day had 90% uptime, how bad would SLA payouts get?* Use this to understand worst-case payout exposure before committing to a high target. ## Confidence values (`p`) -The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. They map to the same presets used when listing: + +**`p` and `sla_sigma_x` use different scales** — do not copy numeric values between them. For example, `p=0.5` (Wide confidence) maps to `sla_sigma_x ≈ 1.0`, not `0.5`. Use the table below to translate between the two. + + +The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. The mappings below match the presets used when listing: | Confidence `p` | Approx. label | Listing equivalent | | --- | --- | --- | | `0.83` | High | `sla_sigma_x ≈ 0.2` | -| `0.67` | Normal (default) | `sla_sigma_x ≈ 0.5` | +| `0.6667` | Normal (default) | `sla_sigma_x ≈ 0.5` | | `0.50` | Wide | `sla_sigma_x ≈ 1.0` | Higher confidence (higher `p`) → tighter spread → lower premiums for clients, but less room for uptime to slip before payouts. @@ -206,23 +257,56 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients | HTTP | `error` | Cause | | --- | --- | --- | +| 401 | — | Missing or invalid Bearer token — see [Authentication](/api-reference/authentication) | | 400 | `invalid_range` | `start_date` is after `end_date` | | 400 | `range_too_large` | More than 366 days requested | -| 400 | `bad_request` | Invalid or out-of-range `r`, `p`, or other query parameter | -| 400 | `invalid_params` | Valid parameters but SLA math could not run (for example, insufficient history) | +| 400 | `bad_request` | Schema, bounds, or unknown-parameter failures (for example, `r` or `p` out of range) | +| 400 | `invalid_params` | Inputs pass validation but fail inside settlement simulation | | 403 | `not_owner` | Machine belongs to another host | | 404 | `machine_not_found` | Invalid `machine_id` | +| 429 | *(rate limited)* | Too many requests — retry with backoff. See [Rate Limits and Errors](/api-reference/rate-limits-and-errors). | ## Recommended workflow -1. **Run a baseline backtest** on a machine with at least a few weeks of rental history. Use your intended target and normal confidence (`p=0.67`). +1. **Run a baseline backtest** on a machine with at least a few weeks of rental history: + - Check your machine's uptime history on the [Host Machines page](https://cloud.vast.ai/host/machines), then use the console SLA preview or backtester — do not rely on the dashboard reliability score alone (see [Machine reliability score vs SLA uptime](/host/sla-offers#machine-reliability-score-vs-sla-uptime)). + - Choose a target at or slightly below your current reliability for your first backtest. + - Use normal confidence (`p=0.6667`). + - If `has_data` is `false`, widen the date range or wait for more rental history. 2. **Check `worst_day_loss`** — can you absorb that payout from a bad day? 3. **Try a higher target** (for example `r=0.99`) and see how `total_sla` changes. 4. **Run a stress test** with `reliability=0.90` at your intended target. -5. **List with headroom** — set `sla_r_claim` above `sla_r_target` on the actual offer for better client pricing than the backtester shows (see [SLA Offers](/host/sla-offers)). +5. **List with headroom** — set `sla_r_claim` above `sla_r_target` on the actual offer for better client pricing than the backtester shows (the backtester uses target = claim; see [SLA Offers](/host/sla-offers)). + +## Fleet workflow + +For hosts automating fleet review. Console-only hosts can run the baseline `curl` once per machine instead. + +1. List machine IDs: `vastai show machines -q` (numeric IDs only) or `vastai show machines --raw | jq -r '.machines[].id'`. +2. Run backtests **sequentially** (one machine at a time) with a short sleep on `429` responses: + +```bash +for id in $(vastai show machines -q); do + curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=$id&r=0.95&p=0.6667" \ + | jq '{machine_id: '"$id"', worst_day_loss: .summary.worst_day_loss, total_sla: .summary.total_sla, has_data: .has_data}' + sleep 1 +done +``` + +Use a `machine_read` key scoped to the machines you own. On `429`, back off per [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Parallel requests are not recommended unless you implement backoff. + +3. Compare `worst_day_loss` and `total_sla` across machines. +4. Apply `sla_r_claim` headroom when listing via the API (see [SLA Offers](/host/sla-offers#api-for-automation)). + +## When stuck + +- **`has_data: false`** — Widen the date range or wait for rental history. +- **`401`** — Check API key permissions (`machine_read`) and Bearer header format. +- **Still stuck** — Ask in the [host Discord](https://discord.gg/hSuEbSQ4X8). ## Related documentation -- [SLA Offers](/host/sla-offers) — listing parameters, economics, and risk scenarios - [SLA Backtest API](/api-reference/host/sla-backtest) — formal API reference for this endpoint +- [SLA Offers](/host/sla-offers) — listing parameters, economics, and risk scenarios - [API permissions](/api-reference/permissions) — `machine_read` scope required diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 86a6c544..ff504280 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -8,40 +8,82 @@ Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listi This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. - -SLA settlement uses an **asymmetric insurance model**: when uptime is good you keep the premium, but when uptime is bad client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. + +SLA settlement is **lopsided by design**: when uptime is good, you keep the premium, but when uptime is bad, client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. Optional: preview SLA economics before listing — use the [SLA backtester](/host/sla-backtester) (API, requires rental history) or the web console SLA preview (**Set Pricing → SLA**). The console preview works on first-time listings. + + + +When a client rents a machine with SLA enabled, they pay a small premium on top of the normal hourly rate. If uptime falls below the promised target, credits are applied to their account automatically. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. +## Choose your path + +| Goal | Start here | +| --- | --- | +| Preview economics and enable SLA in the console | [How it works](#how-it-works-plain-english) → [Listing an SLA offer](#listing-an-sla-offer) | +| Enable or update SLA via API | [Before you enable SLA](#before-you-enable-sla) → [API (for automation)](#api-for-automation) | +| Monitor payouts after listing | [Monitoring SLA after listing](#monitoring-sla-after-listing) | + +## Before you enable SLA + +Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machine appears on **Host → Machines** with no red error status. + +SLA can be enabled on a first-time listing, but you still need base listing fields (GPU price, offer end date, etc.). See [Listing an SLA offer](#listing-an-sla-offer) and [Offer End Date](/host/hosting-overview#offer-end-date). + + +**Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. + + +- Optional: run the [backtester](/host/sla-backtester) after you have weeks of history; otherwise use the web console SLA preview and the economics walkthrough on this page. +- **New or low-history machines:** If the backtester returns `has_data: false`, rely on the web console SLA preview and the economics walkthrough below. Wait for rental history before trusting `worst_day_loss`. Consider wider confidence or lower targets until you have a few weeks of data. + ## How it works (plain English) Think of an SLA offer as three linked ideas: 1. **Reliability target** — the uptime level the listing is priced around (for example, 95% or 99%). 2. **Your reliability claim** — what you believe your machine will actually deliver. -3. **Your confidence** — how sure you are about that claim. A tight confidence means you stand behind a narrow range; a wide confidence means you admit more uncertainty and clients pay a higher premium. +3. **Your confidence** — how sure you are about that claim. Tight confidence means you stand behind a narrow range; wide confidence means a wider defensible range and clients pay a higher premium. When a client rents with SLA enabled: - They pay **compute** (GPU, storage, bandwidth) plus a **daily SLA premium**. - Each day, Vast measures how long the instance was online and settles the SLA. - **Good uptime** → you keep the premium for that day. -- **Bad uptime** → you pay the client from your earnings (up to the day's compute charges plus premium). +- **Bad uptime** → you pay the client from your earnings (up to the day's compute revenue). -Under honest pricing, a host who delivers what they claim should roughly break even on SLA over time — premiums balance payouts. +Under honest pricing, a host who delivers what they claim should roughly break even on SLA over time — premiums and payouts balance. ## SLA parameters -When you list or update a machine, you can set these fields on the offer (via the host console, the [list machine CLI](/host/cli/list-machine), or `PUT /api/v0/machines/create_asks/`): +When you list or update a machine, set SLA fields via the host console or `PUT /api/v0/machines/create_asks/` (see [Listing an SLA offer](#listing-an-sla-offer) below). -| Parameter | API field | What it means | -| --- | --- | --- | -| Reliability target | `sla_r_target` | The coverage level baked into the offer. Set above `0` to enable SLA. Values are fractions between 0 and 1 (for example, `0.95` = 95%). Legacy alias: `sla_reliability`. | -| Reliability claim | `sla_r_claim` | Your advertised belief about machine uptime. Defaults to the reliability target if omitted. Must be **≥** the target. | -| Confidence spread | `sla_sigma_x` | How wide your belief is around the claim. Lower = more confident (cheaper for clients). Defaults to `0.5` if omitted. | +| Parameter | API field | Backtester alias | What it means | +| --- | --- | --- | --- | +| Reliability target | `sla_r_target` | `r` | The uptime level the offer is priced around. Set above `0` to enable SLA. Values are greater than 0 and at most **0.9999** (for example, `0.95` = 95%). Exactly `1.0` is rejected. Legacy alias: `sla_reliability` (deprecated; use `sla_r_target` instead). Avoid sending both. | +| Reliability claim | `sla_r_claim` | — (backtester sets claim = target) | Your advertised belief about machine uptime. Defaults to the reliability target if omitted. Must be **≥** the target. Same bounds as target (greater than 0, at most 0.9999). | +| Confidence spread | `sla_sigma_x` | `p` (different scale — see [backtester](/host/sla-backtester#confidence-values-p)) | How wide your belief is around the claim. Lower = more confident (cheaper for clients). Defaults to `0.5` if omitted. | + + +| Concept | Console | Listing API | Backtester | Client sees | +| --- | --- | --- | --- | --- | +| Reliability target | Target | `sla_r_target` | `r` | Target % (coverage level) | +| Reliability claim | Claim | `sla_r_claim` | (set equal to target in backtester) | — | +| Confidence | Confidence | `sla_sigma_x` | `p` (different scale — do not copy directly) | — | +| All-in hourly price | — | — | — | `dph_total` in search | + +**Confidence is not an uptime target.** It controls how aggressively premiums are priced around your claim. + + +### Machine reliability score vs SLA uptime + +The **reliability score** on the Host Machines page reflects connection and instance-start behavior (and is earnings-weighted). **SLA settlement** measures whether covered instances met your published uptime target for billing purposes. + +Do not assume the dashboard score equals SLA uptime. Use **Set Pricing → SLA** in the console or the backtester on historical data to choose `sla_r_target`, `sla_r_claim`, and confidence — not the Machines-page number alone. ### Confidence presets -If you prefer thinking in confidence rather than `sla_sigma_x`, these presets match the shipped defaults: +If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults. A confidence of ~83% means you believe there is roughly an 83% chance your machine's actual uptime will meet or exceed your claim — higher confidence means lower client premiums. | Label | Approx. confidence | `sla_sigma_x` | Effect on premium | | --- | --- | --- | --- | @@ -53,44 +95,141 @@ If you prefer thinking in confidence rather than `sla_sigma_x`, these presets ma Offers with invalid combinations are rejected at listing time: -- The reliability target must be greater than 0 and at most 1. -- The reliability claim must be between 0 and 1 and must be **≥** the target. +- The reliability target must be greater than 0 and at most **0.9999** when enabling SLA. Set to `0` to disable SLA. +- The reliability claim must be greater than 0, at most **0.9999**, and must be **≥** the target. - Confidence spread must be positive and at most `3.0`. + +If listing is rejected with `error: "invalid_sla_params"`, check the `msg` field against the rules above. Common causes: claim below target, `sla_sigma_x` out of range, values of exactly `1.0`, or invalid partial-update combinations. + + +### SLA and GPU slicing + +SLA settlement applies per rental contract. If your machine has multiple GPU slices rented by different clients (GPU slicing — see **Min GPU** in [Hosting Overview](/host/hosting-overview)), each contract's SLA is settled independently based on the uptime experienced by that instance. + +The backtester replays **machine-level** daily earnings (total compute across all active rentals on that machine). `worst_day_loss` in `summary` reflects the worst simulated day for the whole machine in the replay window — not a single GPU slice in isolation. + +On sliced machines, a full-machine outage can affect every concurrent SLA rental at once. Use `worst_day_loss` as your primary tail-risk metric for the machine, and sanity-check exposure against how many SLA-covered instances you typically run in parallel. Do **not** multiply `worst_day_loss` by contract count — the backtester already models machine-level compute for the replay window. + +To see how many rentals are active on a machine, check the [Host Machines page](https://cloud.vast.ai/host/machines) or run `vastai show machines` and inspect the rented/active instance fields for that `machine_id`. + +### SLA on extended contracts + +When a rental contract is extended (by moving the offer end date forward at the same or lower price), the original SLA parameters remain in effect for the extended period. Changing SLA parameters on the offer does not alter SLA terms on existing contracts — only new rental contracts pick up updated SLA settings. + +Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-covered contracts but does not terminate SLA on existing active contracts — they continue under their original SLA terms until their rental end date. + ## Listing an SLA offer ### Web console -When listing a machine in the [host machines page](https://cloud.vast.ai/host/machines), enable SLA and set your reliability target, claim, and confidence. The console shows how these affect the premium clients will see. +1. Open your machine on the [Host Machines page](https://cloud.vast.ai/host/machines) → **Set Pricing**. +2. Expand **SLA**. +3. Set **Reliability target** (`sla_r_target`), **Reliability claim** (`sla_r_claim`), and **Confidence** (`sla_sigma_x` or a preset). +4. Save and confirm the SLA premium preview before listing. + +#### Web console SLA preview + +In the host console, open **Host Machines** → select your machine → **Set Pricing** → **SLA**. The preview shows estimated SLA premium and payout exposure for the parameters you enter. It is a forward-looking quote, not a historical replay — use the [SLA Backtester](/host/sla-backtester) for history-based simulation. -### CLI and API +### API (for automation) -Pass SLA fields to `vastai list machine` or `PUT /api/v0/machines/create_asks/` (this endpoint creates or updates the listing for your machine): +New hosts: use the web console steps above first. Use the API when you need scripting, partial updates, or fleet automation. + + +SLA listing via `vastai list machine` and `VastAI.list_machine()` is **not yet available** in the published CLI/SDK. Use the REST API below until tooling support is released. + + +#### Before you start + +SLA listing requires the REST API today — CLI and SDK SLA flags are not yet available in published tooling. + +1. Open **Account → API Keys** and create a key. See [Create API Key](/api-reference/accounts/create-api-key). +2. For listing SLA offers, enable **`machine_write`**. For backtesting first, add **`machine_read`**. For post-listing earnings, add **`billing_read`** (one key can include multiple permissions). +3. Use the key as `Authorization: Bearer YOUR_API_KEY` in the `curl` examples below. See [Authentication](/api-reference/authentication). +4. To enable SLA today, use `PUT /api/v0/machines/create_asks/` or **Set Pricing → SLA** in the console. `vastai list machine` hits the same endpoint for non-SLA fields only until CLI SLA flags ship. The listing body field is `machine` (same ID as backtester `machine_id` and earnings `machid`). +5. For the full request/response schema (including `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, and `invalid_sla_params`), see [List Machine](/api-reference/machines/list-machine). + +Listing or updating SLA parameters requires an API key with **`machine_write`** permission. Backtesting requires **`machine_read`**. See [API permissions](/api-reference/permissions). ```bash -vastai list machine 12345 \ - --price_gpu 3.50 \ - --sla_r_target 0.95 \ - --sla_r_claim 0.99 \ - --sla_sigma_x 0.5 +curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "machine": 12345, + "price_gpu": 3.50, + "sla_r_target": 0.95, + "sla_r_claim": 0.99, + "sla_sigma_x": 0.5, + "end_date": 1735689600 + }' ``` -Minimal example (claim and confidence use defaults). Body for `PUT /api/v0/machines/create_asks/`: +Set `end_date` so the offer does not stay open indefinitely — especially important for SLA commitments. See [Offer End Date](/host/hosting-overview#offer-end-date). + +Minimal example (claim and confidence use defaults): ```json { "machine": 12345, "price_gpu": 3.50, + "end_date": 1735689600, "sla_r_target": 0.95 } ``` +Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). + This creates an offer with target `0.95`, claim `0.95`, and confidence spread `0.5`. Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. +**SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: + +```bash +curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"machine": 12345, "sla_r_target": 0.99, "sla_r_claim": 0.995, "sla_sigma_x": 2.0}' +``` + +**Disable SLA on new rentals** — set `sla_r_target` to `0` (active contracts keep their terms). + +#### Common errors + +| Status | Code | When it happens | +| --- | --- | --- | +| 401 | — | Missing or invalid Bearer token | +| 403 | `not_authorized` | API key lacks `machine_write` or other required permission | +| 400 | `invalid_args` | Machine ID not found for your account (includes other hosts' machines) | +| 400 | `invalid_sla_params` | SLA parameters failed validation | +| 400 | `invalid_args` | Malformed or incompatible request body | +| 403 | `machine_locked` | Machine is decommissioned or migration-locked | + +**Success response (200):** + +```json +{ + "success": true, + "you_sent": { "...": "echo of your request body" }, + "results": [ + { + "machine_id": 12345, + "user_id": 67890, + "extended": 1, + "new_contracts": [], + "upd_contracts": [1] + } + ] +} +``` + +- `extended` — integer count of rental contracts extended (read from `results[0]`, not the top level) +- `new_contracts` / `upd_contracts` — arrays of contract IDs + ## Economics walkthrough **Setup:** You list an H100 at **$3.50/hr** GPU price with target **95%**, claim **99%**, and normal confidence (`sla_sigma_x = 0.5`). @@ -100,30 +239,48 @@ Partial updates are supported when editing an existing listing. If you change on | Daily compute (`C`) | ~$84/day ($3.50 × 24 hr) | | SLA premium to client | ~**$0.008/hr** (~$0.20/day) | -This premium is what a client searching for 95% reliability would see added to `dph_total` (dollars per hour, total rental price). +Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst-case payout exposure (`worst_day_loss`), not exact client premiums. For client-visible SLA pricing, use the console **Set Pricing → SLA** preview or inspect `dph_total` in search results. + + +The economics above assume claim (99%) is above target (95%). The [backtester](/host/sla-backtester) is conservative — it sets claim equal to target — so its simulated payouts will differ. Use `worst_day_loss` from the backtester as your tail-risk reference, then adjust expectations when you list with headroom (claim above target). Use the web console SLA preview for the exact premium clients will see in search (`dph_total`). + + +This premium is what a client searching for 95% reliability would see added to the total hourly price in search results (`dph_total` — visible in [Search Offers](/api-reference/search/search-offers) results). ### If you meet your claim -| Measured uptime (simplified) | Client net (per day) | You net (per day) | +| Measured uptime (simplified) | Client SLA cost (per day) | You net (per day) | | --- | --- | --- | | ~100% (excellent day) | −$0.20 (paid premium) | +$0.20 (keep premium) | | ~99% (good day) | −$0.17 | +$0.17 | +Negative client SLA cost = premium paid by the client. Positive = payout received by the client. + You keep most or all of the premium. ### If you miss the target + +Payouts scale relative to the day's compute revenue, not the premium collected. A single bad day at your target boundary can cost as much as 200+ days of collected premiums. Review the economics below and run the [backtester](/host/sla-backtester) before enabling SLA. + + + +Visible client premiums are lower than backtester output when `sla_r_claim` is above `sla_r_target`. Use `worst_day_loss` as your primary tail-risk reference. The table below illustrates payout at the target boundary only. + + These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: -| Measured uptime (simplified) | Client net (per day) | You net (per day) | +| Measured uptime (simplified) | Client SLA cost (per day) | You net (per day) | | --- | --- | --- | | At target (~95%) | ~+$42 | ~−$42 | | Well below target (~90% or less) | ~+$84 (full compute refund) | ~−$84 | -On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged twice for downtime they already did not pay for. Your maximum SLA loss on a single day is capped at that day's compute revenue. +To put the asymmetry in perspective: at ~$0.20/day in premiums, it takes roughly 210 good days to accumulate the $42 you could lose on a single day at the target boundary. The premium is a small fraction of daily compute, while the payout scales against total daily compute revenue. + +On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged a premium on top of compute charges for periods when the instance was down. Your maximum SLA loss on any single settlement day is capped at that day's compute revenue, regardless of how the multi-window aggregation evaluates uptime. -These examples use simplified single-day uptime for illustration. Production settlement aggregates uptime across multiple time windows (from about 1 day to about 3 years of history), so one bad hour does not always produce the maximum payout, and one good day does not instantly erase a long streak of problems. +Production settlement blends recent and historical uptime — not a single raw day — so short outages may not produce the maximum illustrated payout. ## Risk scenarios @@ -146,19 +303,100 @@ Clients pay more because you admit greater uncertainty. Use this if your uptime ### Scheduled maintenance -Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) with sufficient advance notice may be credited back toward uptime, reducing SLA penalties for planned downtime. Unplanned outages count fully. +Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) may be credited back toward uptime, reducing SLA penalties for planned downtime. Unplanned outages count fully toward SLA settlement. + + +Planned maintenance credit is not guaranteed. The platform evaluates advance notice (generally at least 24 hours recommended) and maintenance duration when determining credit eligibility. **Treat any scheduled downtime as a potential SLA payout event when modeling risk.** Contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or email [contact@vast.ai](mailto:contact@vast.ai) before extended maintenance on an SLA-listed machine to confirm credit eligibility. + ## Preview earnings before listing -Use the [SLA Earnings Backtester](/host/sla-backtester) to replay your machine's historical earnings through SLA math and compare simulated premiums and payouts before you enable SLA on a listing. +Use the [SLA Earnings Backtester](/host/sla-backtester) (API-only; requires a `machine_read` API key) to replay historical earnings through SLA math. Console-only hosts can use the web console SLA preview and the economics walkthrough on this page instead. + +## When things go wrong + +- **Listing rejected (`invalid_sla_params`)** — Re-check target, claim, and `sla_sigma_x` against [validation rules](#validation-rules). +- **Unexpected payout** — Review uptime; re-run the backtester with a low `reliability` stress value (for example `0.01`). +- **Severe outage** — Disable SLA on new contracts (`sla_r_target=0`); contact [Discord](https://discord.gg/hSuEbSQ4X8) before relisting. + +## Monitoring SLA after listing + +After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal Time) day boundaries. + +### Console (recommended for day-to-day checks) + +1. Open **Host → Billing** (or **Earnings** / **Reports**). +2. Select the machine and the UTC day range you care about. +3. Look for SLA premium and payout line items alongside compute earnings. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. + +### CLI + +**Linux (GNU date):** + +```bash +vastai show earnings --machine_id --start_date $(date -d '7 days ago' +%F) --end_date $(date +%F) +``` + +**macOS:** + +```bash +vastai show earnings --machine_id --start_date $(date -v-7d +%F) --end_date $(date +%F) +``` + +On Windows, use WSL or the API example below. See [`show earnings`](/cli/reference/show-earnings) for all options. + +### API (automation) + + +**Console users:** Skip this section if you check payouts in **Host → Billing**. No API key is required. + + +**API keys for SLA** + +| Task | Permission | +| --- | --- | +| SLA backtester | `machine_read` | +| List or update SLA on an offer | `machine_write` | +| Post-listing SLA earnings | `billing_read` | + +For API automation only — console users can stop after the Console subsection above. + +`GET /api/v0/users/{user_id}/machine-earnings/` returns SLA fields alongside compute earnings. Requires a **`billing_read`** API key (separate from `machine_read` used for the backtester). See [`show earnings`](/api-reference/billing/show-earnings). + + +When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. + +There is no per-machine daily SLA series in this API. For day-level reconciliation on one machine, use the console earnings report. + + +**Machine-scoped window total:** + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/users/{user_id}/machine-earnings/?machid=12345&last_days=7" \ + | jq '.per_machine[] | select(.machine_id==12345) | {machine_id, sla_earn}' +``` + +**Sign convention** (same as backtester `sla` / `historical_sla`): + +| Field | Good day (meet target) | Bad day (miss target) | +| --- | --- | --- | +| `per_machine[].sla_earn` / `summary.total_sla` | Positive (premium kept) | Negative (payout paid) | +| Fleet `per_day[].sla_earn` | Positive (premium kept) | Negative (payout paid) | + +- `{user_id}` — Your account ID (from **Account → Profile** in the console, or `vastai show user`). +- `sday` / `eday` — UTC day indices (days since 1970-01-01). Prefer `?last_days=N` on the API if you do not want to compute indices manually. +- Settlement is evaluated on UTC day boundaries. + +The backtester's `historical_sla` replays past settlement and is not a live billing feed. For fleet-scale day-level forensics per machine, use the console or poll `per_machine[].sla_earn` over rolling windows. ## Tips for competitive SLA offers - **Set claim above target.** A claim of 99% with a target of 95% produces a much lower premium than matching them both at 95%. - **Tighten confidence only when earned.** Use high confidence (`sla_sigma_x ≈ 0.2`) after you have a strong uptime track record on that machine. - **Keep the machine online during active contracts.** SLA payouts and verification are separate systems, but both respond to downtime. -- **SLA applies to on-demand listings.** [Interruptible](/guides/instances/rental-types) instances use a separate bidding model and are not covered by SLA. -- **Use the [SLA backtester](/host/sla-backtester)** to preview how different targets and confidence levels would have affected past earnings. +- **SLA applies to on-demand rentals only.** It does not apply to interruptible/bid instances or reserved/prepay rentals. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. When a client starts an on-demand rental on an SLA-enabled offer, SLA terms lock for that rental contract and do not change if you later edit the offer. +- **Use the [SLA backtester](/host/sla-backtester) (API-only)** to preview how different targets and confidence levels would have affected past earnings. ## Related documentation diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 8887e2f4..149e8971 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -1,7 +1,11 @@ -list a machine for rent +Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. + +SLA parameters (`--sla_r_target`, `--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. To enable SLA on a listing, use `PUT /api/v0/machines/create_asks/` — see [SLA Offers](/host/sla-offers#api-for-automation). + + ## Usage ```bash @@ -11,7 +15,7 @@ vastai list machine ID [options] ## Arguments - id of machine to list + ID of the machine to list. ## Options @@ -60,24 +64,12 @@ vastai list machine ID [options] Price for disk on volume contract offer. Defaults to price_disk. Invalid if vol_size is 0. (alias: `--vol_price`) - - Client reliability coverage target (0–1). Values above 0 enable SLA on the offer. Set to `0` to disable SLA. Legacy alias: `--sla_reliability`. (alias: `--sla-r-target`) - - - - Host reliability claim (0–1). Must be ≥ `sla_r_target`. Defaults to `sla_r_target` if omitted. (alias: `--sla-r-claim`) - - - - Host confidence spread — how wide your belief is around the claim. Must be greater than 0 and at most 3.0. Lower = tighter confidence and lower client premiums. Defaults to `0.5`. (alias: `--sla-sigma-x`) - - ## Description Performs the same action as pressing the "LIST" button on the site https://cloud.vast.ai/host/machines. -On the end date the listing will expire and your machine will unlist. However any existing client jobs will still remain until ended by their owners. +On the end date the listing will expire and your machine will unlist. However, any existing rental contracts will still remain until ended by their owners. Once you list your machine and it is rented, it is extremely important that you don't interfere with the machine in any way. -If your machine has an active client job and then goes offline, crashes, or has performance problems, this could permanently lower your reliability rating. +If your machine has an active rental contract and then goes offline, crashes, or has performance problems, this could permanently lower your reliability rating. We strongly recommend you test the machine first and only list when ready. ## Examples diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 12bf7112..ffeb2230 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -1,7 +1,11 @@ -List details of a single machine with optional pricing and configuration parameters. +Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. + +SLA parameters (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. To enable SLA on a listing, use `PUT /api/v0/machines/create_asks/` — see [SLA Offers](/host/sla-offers#api-for-automation). + + ## Signature ```python @@ -14,56 +18,41 @@ VastAI.list_machine( discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None, - sla_r_target: Optional[float] = None, - sla_r_claim: Optional[float] = None, - sla_sigma_x: Optional[float] = None, ) -> str ``` ## Parameters - id + Machine ID to list. - price_gpu + GPU rental price in $/hour for active instances. - price_disk + Storage price in $/GB/month for inactive instances. - price_inetu + Upload bandwidth price in $/GB. - price_inetd + Download bandwidth price in $/GB. - discount_rate + Max long-term prepay discount rate fraction (default 0.4). - min_chunk + Minimum GPUs that must be rented together (GPU slicing). - end_date - - - - Reliability coverage target (0–1). Values above 0 enable SLA. - - - - Host reliability claim (0–1). Must be ≥ sla_r_target. - - - - Host confidence spread — how wide your belief is around the claim. Must be greater than 0 and at most 3.0. Lower = tighter confidence. + Offer expiration (Unix timestamp or MM/DD/YYYY). ## Returns @@ -76,19 +65,6 @@ VastAI.list_machine( from vastai import VastAI client = VastAI(api_key="YOUR_API_KEY") -result = client.list_machine(id=12345) -print(result) -``` - -With SLA enabled: - -```python -result = client.list_machine( - id=12345, - price_gpu=3.50, - sla_r_target=0.95, - sla_r_claim=0.99, - sla_sigma_x=0.5, -) +result = client.list_machine(id=12345, price_gpu=3.50) print(result) ``` From 7fd5ce5c28de2ab402d49444545d9354c30d3b83 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:19:01 -0700 Subject: [PATCH 04/45] docs(sla): address doc-review consensus (cycle 2) Clarify economics sign convention, console LIST step, dph_total, OpenAPI SLA CLI caveat, fleet backtest error handling, and webhook subscription key. Co-authored-by: Cursor --- api-reference/openapi.yaml | 10 ++++-- api-reference/openapi/yaml/list_machine.yaml | 6 ++-- host/hosting-overview.mdx | 2 +- host/sla-backtester.mdx | 11 +++++-- host/sla-offers.mdx | 34 ++++++++++++++------ snippets/host/cli/list-machine.mdx | 2 +- snippets/host/sdk/list-machine.mdx | 2 +- 7 files changed, 47 insertions(+), 20 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 875b2e55..cc2c35ef 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4499,11 +4499,17 @@ paths: description: 'Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform. - Allows setting pricing, minimum GPU requirements, end date, discount rates, + Allows setting offer pricing, rental types, end dates, discount rates, and SLA parameters. - CLI Usage: `vastai list machine [options]`' + SLA request-body fields (sla_r_target, sla_r_claim, sla_sigma_x) are + supported on this REST endpoint. The published CLI and SDK do not yet expose + them — use the host console (Set Pricing → SLA) or REST/curl until CLI/SDK + support ships. + + + CLI Usage (non-SLA fields): `vastai list machine [options]`' security: - BearerAuth: [] requestBody: diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index b5ab49ed..93d860b0 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -12,9 +12,11 @@ paths: summary: list machine description: | Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform. - Allows setting pricing, minimum GPU requirements, end date, discount rates, and SLA parameters. + Allows setting offer pricing, rental types, end dates, discount rates, and SLA parameters. - CLI Usage: `vastai list machine [options]` + SLA request-body fields (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are supported on this REST endpoint. The published CLI and SDK do not yet expose them — use the host console (**Set Pricing → SLA**) or REST/`curl` until CLI/SDK support ships. + + CLI Usage (non-SLA fields): `vastai list machine [options]` security: - BearerAuth: [] requestBody: diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 27a08dc0..27bee603 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -237,7 +237,7 @@ Remember that a single machine may have multiple active rental contracts from di For unplanned or unscheduled maintenance, use the CLI and the [`vastai schedule maint`](/host/cli/schedule-maint) command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. -For SLA-listed machines, scheduled downtime may still count against your reliability target. Uptime credit for maintenance is evaluated case by case and is not guaranteed — give at least 24 hours' notice before extended work. When you schedule maintenance, clients may be notified via [Host Notifications](/host/notifications) (including `maintenance_scheduled` webhooks). See [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). +For SLA-listed machines, scheduled downtime may still count against your reliability target. Uptime credit for maintenance is evaluated case by case and is not guaranteed — give at least 24 hours' notice before extended work. When you schedule maintenance, clients may be notified via [Host Notifications](/host/notifications) — subscribe to `host:maintenance_scheduled` (payloads use `notif_type: maintenance_scheduled`). See [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). ## Uninstalling diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 1dfeb644..993f2f2a 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -282,14 +282,19 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients For hosts automating fleet review. Console-only hosts can run the baseline `curl` once per machine instead. +```bash +export VAST_API_KEY="YOUR_API_KEY" +``` + 1. List machine IDs: `vastai show machines -q` (numeric IDs only) or `vastai show machines --raw | jq -r '.machines[].id'`. -2. Run backtests **sequentially** (one machine at a time) with a short sleep on `429` responses: +2. Run backtests **sequentially** (one machine at a time): ```bash for id in $(vastai show machines -q); do - curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + resp=$(curl -sf -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=$id&r=0.95&p=0.6667" \ - | jq '{machine_id: '"$id"', worst_day_loss: .summary.worst_day_loss, total_sla: .summary.total_sla, has_data: .has_data}' + || echo '{"error":"request_failed"}') + echo "$resp" | jq '{machine_id: '"$id"', worst_day_loss: .summary.worst_day_loss, total_sla: .summary.total_sla, has_data: .has_data, error: .error}' sleep 1 done ``` diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index ff504280..41a917da 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -70,11 +70,15 @@ When you list or update a machine, set SLA fields via the host console or `PUT / | Reliability target | Target | `sla_r_target` | `r` | Target % (coverage level) | | Reliability claim | Claim | `sla_r_claim` | (set equal to target in backtester) | — | | Confidence | Confidence | `sla_sigma_x` | `p` (different scale — do not copy directly) | — | -| All-in hourly price | — | — | — | `dph_total` in search | +| All-in hourly price | — | — | — | `dph_total` (dollars per hour total in search — compute plus SLA premium when enabled) | **Confidence is not an uptime target.** It controls how aggressively premiums are priced around your claim. + +**Confidence in one sentence:** The **preset name** (High / Normal / Wide) controls how **tight your claim spread** is around your target, which changes **client premiums** (tighter → lower premiums, wider → higher premiums). In the console, use the labeled presets rather than raw numbers. The ~83% figure describes how often your machine's actual uptime is expected to meet or exceed your claim — not a separate setting. + + ### Machine reliability score vs SLA uptime The **reliability score** on the Host Machines page reflects connection and instance-start behavior (and is earnings-weighted). **SLA settlement** measures whether covered instances met your published uptime target for billing purposes. @@ -127,6 +131,7 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove 2. Expand **SLA**. 3. Set **Reliability target** (`sla_r_target`), **Reliability claim** (`sla_r_claim`), and **Confidence** (`sla_sigma_x` or a preset). 4. Save and confirm the SLA premium preview before listing. +5. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. #### Web console SLA preview @@ -144,6 +149,8 @@ SLA listing via `vastai list machine` and `VastAI.list_machine()` is **not yet a SLA listing requires the REST API today — CLI and SDK SLA flags are not yet available in published tooling. +Before you call this endpoint, your machine must appear on **Host → Machines** with the daemon connected. This call creates or updates the **offer**, not machine registration. See [Host setup](https://cloud.vast.ai/host/setup/). + 1. Open **Account → API Keys** and create a key. See [Create API Key](/api-reference/accounts/create-api-key). 2. For listing SLA offers, enable **`machine_write`**. For backtesting first, add **`machine_read`**. For post-listing earnings, add **`billing_read`** (one key can include multiple permissions). 3. Use the key as `Authorization: Bearer YOUR_API_KEY` in the `curl` examples below. See [Authentication](/api-reference/authentication). @@ -239,7 +246,7 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ | Daily compute (`C`) | ~$84/day ($3.50 × 24 hr) | | SLA premium to client | ~**$0.008/hr** (~$0.20/day) | -Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst-case payout exposure (`worst_day_loss`), not exact client premiums. For client-visible SLA pricing, use the console **Set Pricing → SLA** preview or inspect `dph_total` in search results. +Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst-case payout exposure (`worst_day_loss`), not exact client premiums. For client-visible SLA pricing, use the console **Set Pricing → SLA** preview or inspect **`dph_total`** (dollars per hour total in search — compute plus SLA premium when enabled). The economics above assume claim (99%) is above target (95%). The [backtester](/host/sla-backtester) is conservative — it sets claim equal to target — so its simulated payouts will differ. Use `worst_day_loss` from the backtester as your tail-risk reference, then adjust expectations when you list with headroom (claim above target). Use the web console SLA preview for the exact premium clients will see in search (`dph_total`). @@ -249,13 +256,13 @@ This premium is what a client searching for 95% reliability would see added to t ### If you meet your claim -| Measured uptime (simplified) | Client SLA cost (per day) | You net (per day) | +In the tables below, **Client pays / receives** uses negative values when the client pays you a premium (money you keep) and positive values when the client receives a payout. + +| Measured uptime (simplified) | Client pays / receives (per day) | You net (per day) | | --- | --- | --- | -| ~100% (excellent day) | −$0.20 (paid premium) | +$0.20 (keep premium) | +| ~100% (excellent day) | −$0.20 (premium paid to you) | +$0.20 (keep premium) | | ~99% (good day) | −$0.17 | +$0.17 | -Negative client SLA cost = premium paid by the client. Positive = payout received by the client. - You keep most or all of the premium. ### If you miss the target @@ -270,7 +277,7 @@ Visible client premiums are lower than backtester output when `sla_r_claim` is a These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: -| Measured uptime (simplified) | Client SLA cost (per day) | You net (per day) | +| Measured uptime (simplified) | Client pays / receives (per day) | You net (per day) | | --- | --- | --- | | At target (~95%) | ~+$42 | ~−$42 | | Well below target (~90% or less) | ~+$84 (full compute refund) | ~−$84 | @@ -325,9 +332,9 @@ After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal ### Console (recommended for day-to-day checks) -1. Open **Host → Billing** (or **Earnings** / **Reports**). -2. Select the machine and the UTC day range you care about. -3. Look for SLA premium and payout line items alongside compute earnings. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. +1. Open **Host → Billing** (or **Earnings** / **Reports**) for the machine and UTC date range. +2. Look for rows labeled **SLA premium** (client payments you keep) and **SLA payout** (amounts you owe after a miss). Exact menu names may vary; filter by machine ID and date if needed. +3. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. ### CLI @@ -345,6 +352,13 @@ vastai show earnings --machine_id --start_date $(date -v-7d +%F) --end_date On Windows, use WSL or the API example below. See [`show earnings`](/cli/reference/show-earnings) for all options. +```bash +vastai show earnings --machine_id --start_date $(date -d '7 days ago' +%F) --end_date $(date +%F) --raw \ + | jq '.per_machine[] | {machine_id, sla_earn}' +``` + +Positive `sla_earn` = net SLA premium you kept that period; negative = net payout you owe. See the sign-convention table in the API subsection below. + ### API (automation) diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 149e8971..fb39f22c 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. -SLA parameters (`--sla_r_target`, `--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. To enable SLA on a listing, use `PUT /api/v0/machines/create_asks/` — see [SLA Offers](/host/sla-offers#api-for-automation). +SLA parameters (`--sla_r_target`, `--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). ## Usage diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index ffeb2230..306265f0 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. -SLA parameters (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. To enable SLA on a listing, use `PUT /api/v0/machines/create_asks/` — see [SLA Offers](/host/sla-offers#api-for-automation). +SLA parameters (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). ## Signature From fa5ff959c5d4a62b108987726ec6a9aa7ef58c57 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:24:50 -0700 Subject: [PATCH 05/45] docs(sla): address doc-review consensus (cycle 3) Document console Save-then-LIST vs REST publish, host-centric economics tables, earnings rate limits, merge semantics, and maintenance webhooks. Co-authored-by: Cursor --- host/hosting-overview.mdx | 4 +-- host/sla-backtester.mdx | 10 ++++-- host/sla-offers.mdx | 51 ++++++++++++++++++++---------- snippets/host/cli/list-machine.mdx | 2 ++ snippets/host/sdk/list-machine.mdx | 2 ++ 5 files changed, 47 insertions(+), 22 deletions(-) diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 27bee603..b3b95cdf 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -233,11 +233,11 @@ The proper way to perform maintenance on your machine is to wait until all activ Unlisting the offer will prevent new rental contracts from being created, but does not affect existing ones. However if you have active rental contracts, you could set the offer end date to match the latest rental end date, allowing new clients to rent instances that end at the same date. Once the end date is reached, you can then unlist the machine and then perform maintenance. -Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored, you cannot take the machine offline until every active rental contract has ended. +Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored. You cannot take the machine offline until every active rental contract has ended. For unplanned or unscheduled maintenance, use the CLI and the [`vastai schedule maint`](/host/cli/schedule-maint) command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. -For SLA-listed machines, scheduled downtime may still count against your reliability target. Uptime credit for maintenance is evaluated case by case and is not guaranteed — give at least 24 hours' notice before extended work. When you schedule maintenance, clients may be notified via [Host Notifications](/host/notifications) — subscribe to `host:maintenance_scheduled` (payloads use `notif_type: maintenance_scheduled`). See [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). +For SLA-listed machines, scheduled downtime may still count against your reliability target. Uptime credit for maintenance is evaluated case by case and is not guaranteed — give at least 24 hours' notice before extended work. When you schedule maintenance with `vastai schedule maint`, clients with active rentals may be notified automatically. If you want your own alerts (email, webhook, etc.), optionally subscribe via [Host Notifications](/host/notifications) — for example, to `host:maintenance_scheduled`. See [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). ## Uninstalling diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 993f2f2a..dee0b7d8 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -38,7 +38,7 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). 3. For each active day, it computes GPU, storage, and bandwidth earnings plus simulated SLA host earnings. 4. It returns a day-by-day breakdown and summary totals. -**Simulated vs listing parameters.** In the backtester, reliability target and claim are both set to **`r`**. When you actually list a machine, you can set **`sla_r_claim` above `sla_r_target`** for lower client premiums. +**Simulated vs listing parameters.** In the backtester, reliability target and claim are both set to **`r`** — the backtester cannot set `sla_r_claim` above `sla_r_target`. Claim-headroom simulation is console-only today. When you actually list a machine, you can set **`sla_r_claim` above `sla_r_target`** for lower client premiums. Workflow: backtest `worst_day_loss` at your target, then verify visible premiums in **Set Pricing → SLA** (or `dph_total` in search) before listing with claim above target. **Active vs idle days.** **Idle days** are days with no rental earnings on the machine (no active compute rental). These days typically produce no SLA premium or payout in the simulation. Days with no rental activity appear in the results as zero-filled rows but do not count toward `covered_days`. Only days with actual earnings are replayed through SLA math. @@ -280,7 +280,7 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients ## Fleet workflow -For hosts automating fleet review. Console-only hosts can run the baseline `curl` once per machine instead. +This section is for hosts automating fleet review. Console-only hosts can run the baseline `curl` once per machine instead. ```bash export VAST_API_KEY="YOUR_API_KEY" @@ -294,7 +294,11 @@ for id in $(vastai show machines -q); do resp=$(curl -sf -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=$id&r=0.95&p=0.6667" \ || echo '{"error":"request_failed"}') - echo "$resp" | jq '{machine_id: '"$id"', worst_day_loss: .summary.worst_day_loss, total_sla: .summary.total_sla, has_data: .has_data, error: .error}' + if echo "$resp" | jq -e '.error' >/dev/null 2>&1; then + echo "machine_id=$id error: $(echo "$resp" | jq -r '.error')" + else + echo "$resp" | jq '{machine_id: '"$id"', worst_day_loss: .summary.worst_day_loss, total_sla: .summary.total_sla, has_data: .has_data}' + fi sleep 1 done ``` diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 41a917da..dec080af 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -9,7 +9,7 @@ Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listi This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. -SLA settlement is **lopsided by design**: when uptime is good, you keep the premium, but when uptime is bad, client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. Optional: preview SLA economics before listing — use the [SLA backtester](/host/sla-backtester) (API, requires rental history) or the web console SLA preview (**Set Pricing → SLA**). The console preview works on first-time listings. +SLA settlement is **lopsided by design**: when uptime is good, you keep the premium, but when uptime is bad, client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. You can optionally preview SLA economics before listing — use the [SLA backtester](/host/sla-backtester) (API, requires rental history) or the web console SLA preview (**Set Pricing → SLA**). The console preview works on first-time listings. @@ -28,6 +28,8 @@ When a client rents a machine with SLA enabled, they pay a small premium on top Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machine appears on **Host → Machines** with no red error status. +Before enabling SLA, finish normal listing setup: test your machine, set GPU price and offer end date, choose on-demand vs interruptible, and understand [Testing your own machine](/host/hosting-overview#testing-your-own-machine) and offer terms in [Hosting overview](/host/hosting-overview). + SLA can be enabled on a first-time listing, but you still need base listing fields (GPU price, offer end date, etc.). See [Listing an SLA offer](#listing-an-sla-offer) and [Offer End Date](/host/hosting-overview#offer-end-date). @@ -60,7 +62,7 @@ When you list or update a machine, set SLA fields via the host console or `PUT / | Parameter | API field | Backtester alias | What it means | | --- | --- | --- | --- | -| Reliability target | `sla_r_target` | `r` | The uptime level the offer is priced around. Set above `0` to enable SLA. Values are greater than 0 and at most **0.9999** (for example, `0.95` = 95%). Exactly `1.0` is rejected. Legacy alias: `sla_reliability` (deprecated; use `sla_r_target` instead). Avoid sending both. | +| Reliability target | `sla_r_target` | `r` | The uptime level the offer is priced around. Set above `0` to enable SLA. Values are greater than 0 and at most **0.9999** (for example, `0.95` = 95%). Exactly `1.0` is rejected. Legacy alias: `sla_reliability` (deprecated; use `sla_r_target` instead). If both are sent, `sla_r_target` takes precedence. | | Reliability claim | `sla_r_claim` | — (backtester sets claim = target) | Your advertised belief about machine uptime. Defaults to the reliability target if omitted. Must be **≥** the target. Same bounds as target (greater than 0, at most 0.9999). | | Confidence spread | `sla_sigma_x` | `p` (different scale — see [backtester](/host/sla-backtester#confidence-values-p)) | How wide your belief is around the claim. Lower = more confident (cheaper for clients). Defaults to `0.5` if omitted. | @@ -133,6 +135,10 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove 4. Save and confirm the SLA premium preview before listing. 5. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. + +In the web console, **Set Pricing → Save** stores SLA settings; clicking **LIST** publishes the offer to search. `PUT /api/v0/machines/create_asks/` performs both steps in one request — it creates or updates the **live listing** (same as pressing **LIST** or running `vastai list machine`), not a save-only draft. + + #### Web console SLA preview In the host console, open **Host Machines** → select your machine → **Set Pricing** → **SLA**. The preview shows estimated SLA premium and payout exposure for the parameters you enter. It is a forward-looking quote, not a historical replay — use the [SLA Backtester](/host/sla-backtester) for history-based simulation. @@ -192,6 +198,8 @@ This creates an offer with target `0.95`, claim `0.95`, and confidence spread `0 Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. + +Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. For fleet automation, prefer read-modify-write: `vastai show machines` → merge → `PUT /api/v0/machines/create_asks/`. **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -246,22 +254,22 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ | Daily compute (`C`) | ~$84/day ($3.50 × 24 hr) | | SLA premium to client | ~**$0.008/hr** (~$0.20/day) | -Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst-case payout exposure (`worst_day_loss`), not exact client premiums. For client-visible SLA pricing, use the console **Set Pricing → SLA** preview or inspect **`dph_total`** (dollars per hour total in search — compute plus SLA premium when enabled). +Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst single-day payout exposure (`worst_day_loss`), not exact client premiums. For authoritative client-visible premiums, use **Set Pricing → SLA** in the console or **`dph_total`** in search offers — not backtester `total_sla` when claim exceeds target. -The economics above assume claim (99%) is above target (95%). The [backtester](/host/sla-backtester) is conservative — it sets claim equal to target — so its simulated payouts will differ. Use `worst_day_loss` from the backtester as your tail-risk reference, then adjust expectations when you list with headroom (claim above target). Use the web console SLA preview for the exact premium clients will see in search (`dph_total`). +The economics above assume **claim above target** (headroom): claim (99%) is above target (95%), so clients see lower premiums than if both matched. The [backtester](/host/sla-backtester) cannot simulate claim headroom — it sets claim equal to target — so its simulated premiums will be higher. Use `worst_day_loss` from the backtester as your worst single-day payout reference, then verify visible premiums in **Set Pricing → SLA** (or `dph_total` in search) before listing with claim above target. -This premium is what a client searching for 95% reliability would see added to the total hourly price in search results (`dph_total` — visible in [Search Offers](/api-reference/search/search-offers) results). +This premium is what a client searching for 95% reliability would see added to the total hourly price in search results (`dph_total` — visible in the console SLA preview or [Search Offers](/api-reference/search/search-offers) results). ### If you meet your claim -In the tables below, **Client pays / receives** uses negative values when the client pays you a premium (money you keep) and positive values when the client receives a payout. +**You net** uses host earnings signs: positive = premium you kept; negative = payout you owed the client. -| Measured uptime (simplified) | Client pays / receives (per day) | You net (per day) | -| --- | --- | --- | -| ~100% (excellent day) | −$0.20 (premium paid to you) | +$0.20 (keep premium) | -| ~99% (good day) | −$0.17 | +$0.17 | +| Measured uptime (simplified) | You net (per day) | +| --- | --- | +| ~100% (excellent day) | +$0.20 (keep premium) | +| ~99% (good day) | +$0.17 (keep premium) | You keep most or all of the premium. @@ -272,15 +280,15 @@ Payouts scale relative to the day's compute revenue, not the premium collected. -Visible client premiums are lower than backtester output when `sla_r_claim` is above `sla_r_target`. Use `worst_day_loss` as your primary tail-risk reference. The table below illustrates payout at the target boundary only. +Visible client premiums are lower than backtester output when `sla_r_claim` is above `sla_r_target`. Use `worst_day_loss` as your worst single-day payout reference. The table below illustrates payout at the target boundary only. These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: -| Measured uptime (simplified) | Client pays / receives (per day) | You net (per day) | -| --- | --- | --- | -| At target (~95%) | ~+$42 | ~−$42 | -| Well below target (~90% or less) | ~+$84 (full compute refund) | ~−$84 | +| Measured uptime (simplified) | You net (per day) | +| --- | --- | +| At target (~95%) | −$42 (payout you owe) | +| Well below target (~90% or less) | −$84 (full compute refund owed) | To put the asymmetry in perspective: at ~$0.20/day in premiums, it takes roughly 210 good days to accumulate the $42 you could lose on a single day at the target boundary. The premium is a small fraction of daily compute, while the payout scales against total daily compute revenue. @@ -334,7 +342,12 @@ After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal 1. Open **Host → Billing** (or **Earnings** / **Reports**) for the machine and UTC date range. 2. Look for rows labeled **SLA premium** (client payments you keep) and **SLA payout** (amounts you owe after a miss). Exact menu names may vary; filter by machine ID and date if needed. -3. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. +3. Settlement uses **UTC** calendar days — local-time downtime may appear on the adjacent UTC day. +4. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. + + +SLA daily settlement (premium kept / payout owed) does not currently emit host webhooks. Monitor via console billing or poll `machine-earnings`; settlements align to UTC calendar days. + ### CLI @@ -377,10 +390,14 @@ For API automation only — console users can stop after the Console subsection `GET /api/v0/users/{user_id}/machine-earnings/` returns SLA fields alongside compute earnings. Requires a **`billing_read`** API key (separate from `machine_read` used for the backtester). See [`show earnings`](/api-reference/billing/show-earnings). +This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request per second per IP; back off on HTTP 429. For day-level per-machine reconciliation at scale, prefer console billing reports over high-frequency API polling. + When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. There is no per-machine daily SLA series in this API. For day-level reconciliation on one machine, use the console earnings report. + +**Fleet operators:** There is no per-machine daily SLA series in the API. Use console day-level reports per machine for reconciliation, or poll `per_machine[].sla_earn` with `last_days=1` per `machid` (mind UTC day boundaries and rate limits). Expect ~N requests per poll cycle for N machines. **Machine-scoped window total:** @@ -402,7 +419,7 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ - `sday` / `eday` — UTC day indices (days since 1970-01-01). Prefer `?last_days=N` on the API if you do not want to compute indices manually. - Settlement is evaluated on UTC day boundaries. -The backtester's `historical_sla` replays past settlement and is not a live billing feed. For fleet-scale day-level forensics per machine, use the console or poll `per_machine[].sla_earn` over rolling windows. +The backtester's `historical_sla` replays past settlement and is not a live billing feed. For fleet-scale day-by-day review per machine, use the console or poll `per_machine[].sla_earn` over rolling windows. ## Tips for competitive SLA offers diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index fb39f22c..df1ab3f6 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -4,6 +4,8 @@ Lists a machine for rent. SLA parameters (`--sla_r_target`, `--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). + +For SLA listing via REST, see [SLA Offers — API (for automation)](/host/sla-offers#api-for-automation). Volume and duration options below map to REST request fields on `create_asks/`. ## Usage diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 306265f0..ce4562ff 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -4,6 +4,8 @@ Lists a machine for rent with optional pricing and configuration parameters. SLA parameters (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). + +Volume and duration listing parameters (`vol_size`, `vol_price`, `duration`, `price_min_bid`) require the CLI or REST API today — they are not in the SDK signature below. ## Signature From 571aea5d86f500508f581f2fa5ecfdce9453a496 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:32:11 -0700 Subject: [PATCH 06/45] docs(sla): address doc-review consensus (cycle 4) Fix API error shapes, UTC day-index docs, confidence/claim clarity, economics table wording, and host overview SLA publish steps. Co-authored-by: Cursor --- api-reference/openapi.yaml | 14 ++-- api-reference/openapi/yaml/list_machine.yaml | 14 ++-- host/hosting-overview.mdx | 14 +++- host/sla-backtester.mdx | 27 ++++--- host/sla-offers.mdx | 80 ++++++++++++-------- 5 files changed, 95 insertions(+), 54 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index cc2c35ef..2cedda7f 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4646,19 +4646,22 @@ paths: type: string example: No such machine(s) for your account '401': - description: Unauthorized + description: Unauthorized — missing permission or invalid API key content: application/json: schema: type: object properties: + success: + type: boolean + example: false error: type: string msg: type: string - example: Missing or invalid API key + example: Your key lacks the machine_write permission group '403': - description: Forbidden + description: Forbidden — machine locked content: application/json: schema: @@ -4667,12 +4670,11 @@ paths: error: type: string enum: - - not_authorized - machine_locked - example: not_authorized + example: machine_locked msg: type: string - example: API key lacks machine_write permission + example: Machine is decommissioned or migration-locked tags: - Machines operationId: listMachine diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index 93d860b0..0a10d33d 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -153,19 +153,22 @@ paths: type: string example: No such machine(s) for your account '401': - description: Unauthorized + description: Unauthorized — missing permission or invalid API key content: application/json: schema: type: object properties: + success: + type: boolean + example: false error: type: string msg: type: string - example: Missing or invalid API key + example: Your key lacks the machine_write permission group '403': - description: Forbidden + description: Forbidden — machine locked content: application/json: schema: @@ -174,12 +177,11 @@ paths: error: type: string enum: - - not_authorized - machine_locked - example: not_authorized + example: machine_locked msg: type: string - example: API key lacks machine_write permission + example: Machine is decommissioned or migration-locked tags: - Machines components: diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index b3b95cdf..2bd57fba 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -47,7 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) - the offer end date, which determines how long the offer accepts new rental contracts -- **SLA (optional):** A reliability guarantee that clients can pay a premium for. Configure via **Set Pricing → SLA** in the console or the REST API — SLA parameters are not yet available in the published CLI/SDK. See [SLA Offers](/host/sla-offers) for parameters and field names. +- **SLA (optional):** Optional uptime coverage for on-demand rentals. Configure in **Set Pricing → SLA**, save pricing, then click **LIST** to publish the offer. SLA parameters are not yet available in the published CLI/SDK. See [Listing an SLA offer → Web console](/host/sla-offers#web-console). The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. @@ -237,7 +237,15 @@ Remember that a single machine may have multiple active rental contracts from di For unplanned or unscheduled maintenance, use the CLI and the [`vastai schedule maint`](/host/cli/schedule-maint) command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. -For SLA-listed machines, scheduled downtime may still count against your reliability target. Uptime credit for maintenance is evaluated case by case and is not guaranteed — give at least 24 hours' notice before extended work. When you schedule maintenance with `vastai schedule maint`, clients with active rentals may be notified automatically. If you want your own alerts (email, webhook, etc.), optionally subscribe via [Host Notifications](/host/notifications) — for example, to `host:maintenance_scheduled`. See [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). +### If you have SLA enabled on this machine + +SLA-listed machines have additional maintenance obligations: + +- Give at least **24 hours' notice** before planned downtime when possible. +- Use [`vastai schedule maint`](/host/cli/schedule-maint) and configure [Host Notifications](/host/notifications) for `host:maintenance_scheduled` if you want your own alerts. +- Uptime credits during maintenance are evaluated case by case — see [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). + +General maintenance guidance above applies to all hosts regardless of SLA. ## Uninstalling @@ -269,7 +277,7 @@ Verification is conducted in a randomized and automated fashion. We only run man ### How does verification work? -Verification is mostly for higher end machines, mining rigs may never be verified. Verification is also based on supply vs demand and is machine/GPU specific. Right now the only machines which can expect fast verification are \$10k+: H100 or A100 80GB - if not tested quickly in a day or so let us know. 8x4090, 4xA6000 - should be tested in less than a week, especially if you have a number of them. The only manual verification tests are for datacenters and high-end machines. For everything else we run more random auto verification roughly about once a week. For datacenter partner inquiries email us at [contact@vast.ai](mailto:contact@vast.ai) directly. +Verification timing varies by hardware tier, machine value, and marketplace demand. High-end GPUs are generally prioritized, but there is no fixed public schedule. Most verification is automatic; manual verification is used for some higher-end systems. See [Understanding Verification](/host/understanding-verification) for what to expect and how to prepare your machine. For datacenter partner inquiries, email [contact@vast.ai](mailto:contact@vast.ai). ### How do I gain datacenter status? diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index dee0b7d8..b0c3915e 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -4,10 +4,16 @@ description: "Replay your machine's historical earnings through SLA math to prev "canonical": "/host/sla-backtester" --- -The **SLA earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability target **`r`** and confidence level **`p`**, how would that have affected my earnings on this machine over the last few months?* (**`r`** = reliability target; **`p`** = host confidence — both defined in [Query parameters](#query-parameters) below.) +The **SLA (Service Level Agreement) earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability target **`r`** and confidence level **`p`**, how would that have affected my earnings on this machine over the last few months?* + +**Console hosts:** use **Set Pricing → SLA** in the web console to preview premiums — you do not need this API. + +**API hosts:** this endpoint replays historical earnings through SLA math to estimate premiums and worst-day payout risk before listing. (**`r`** = reliability target; **`p`** = host confidence — both defined in [Query parameters](#query-parameters) below.) It replays your machine's **real historical compute earnings and uptime** through the same SLA settlement math used in production, then compares the simulated result to what you actually earned from SLA (if anything). +See [Choose your path](#choose-your-path) below. + **Don't want to use the API?** The backtester is optional. Use the web console SLA preview and the economics walkthrough on [SLA Offers](/host/sla-offers#listing-an-sla-offer) to evaluate SLA before listing. The backtester is for hosts who want historical replay via the API. @@ -57,7 +63,7 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). 1. Open **Account → API Keys** in the console and create a key with **`machine_read`** enabled. 2. Copy the token and use `Authorization: Bearer YOUR_API_KEY` in the examples below. See [Create API Key](/api-reference/accounts/create-api-key) and [Authentication](/api-reference/authentication). 3. Find your machine ID on the [Host Machines page](https://cloud.vast.ai/host/machines). The machine must have at least a few weeks of rental activity — new or idle machines should use the console **Set Pricing → SLA** preview instead (the backtester returns `has_data: false` without sufficient history). -4. Run the baseline `curl` below (default date range — no custom dates required) and check `has_data` in the response. +4. Run the baseline request in [Example request](#example-request) and check `has_data` in the response. ## API reference @@ -108,8 +114,9 @@ curl -s -H "Authorization: Bearer YOUR_API_KEY" \ Custom date range (optional — Jan–Apr 2024 for illustration): ```bash -# start_date = Jan 1, 2024; end_date = Apr 1, 2024 -# Tip: on Linux, `date -d '2024-01-01' +%s`; on macOS, `date -j -f '%Y-%m-%d' '2024-01-01' +%s` +# start_date = Jan 1, 2024 UTC; end_date = Apr 1, 2024 UTC +# Linux: date -u -d '2024-01-01' +%s +# macOS: date -u -j -f '%Y-%m-%d' '2024-01-01' +%s # On Windows, use WSL or an online epoch converter. curl -s -H "Authorization: Bearer YOUR_API_KEY" \ "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.95&p=0.6667&start_date=1704067200&end_date=1711929600" @@ -187,7 +194,7 @@ A successful response looks like this (fields abbreviated): | Field | Meaning | | --- | --- | | `has_data` | `true` if at least one day in the range had earnings to replay. When `false`, there was no billable rental activity in the range: `covered_days` is `0`, `skipped_days` equals the number of days in the requested window, `daily_results` contains one zero-filled row per day in the window (not an empty array), summary totals are `0.0`, and top-level `reliability` is `null`. Try a wider window or a machine with more rental history. | -| `start_day`, `end_day` | UTC day indices (days since January 1, 1970). Same encoding as `daily_results[].day`. Multiply by 86400 for a Unix timestamp. For example, day `19723` × 86400 = `1704067200` = January 1, 2024 UTC. Most hosts can ignore these and use `start_date`/`end_date` in requests. | +| `start_day`, `end_day` | UTC day indices. The API computes `day = floor(epoch_seconds / 86400)`. Same encoding as `daily_results[].day`. To convert a day index to an approximate UTC date: `date -u -d "@$((day * 86400))" +%Y-%m-%d` (Linux). Do not assume `day × 86400` equals UTC midnight for that calendar day. Most hosts can ignore these and use `start_date`/`end_date` in requests. | | `covered_days` | Days with rental activity replayed through SLA math | | `skipped_days` | Days in the range with no activity (zero-filled in `daily_results`) | | `reliability` | Actual uptime ratio over the range (`total uptime / total active time`) | @@ -202,7 +209,7 @@ A successful response looks like this (fields abbreviated): | `sla` | **Simulated SLA host earnings** for the day. Positive = you keep premium; negative = you pay the client | | `historical_sla` | What you **actually** earned from SLA that day (signed). Zero if you were not offering SLA | -Plot `sla` over time to see which days would have helped or hurt under the chosen parameters. Compare against `historical_sla` to see how simulated economics differ from reality. +Review `sla` day by day in `daily_results` to see which days would have helped or hurt under the chosen parameters. Compare against `historical_sla` to see how simulated economics differ from reality. ### Summary fields @@ -255,14 +262,16 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients ## Error responses -| HTTP | `error` | Cause | +| HTTP | `error` / shape | Cause | | --- | --- | --- | -| 401 | — | Missing or invalid Bearer token — see [Authentication](/api-reference/authentication) | +| 403 | `auth_error` | Authorization header missing or invalid session | +| 401 | `auth_error` | API key invalid | +| 401 | authorization `msg` | Valid key but missing `machine_read` (or other scope denial) | +| 403 | `not_owner` | Machine belongs to another host | | 400 | `invalid_range` | `start_date` is after `end_date` | | 400 | `range_too_large` | More than 366 days requested | | 400 | `bad_request` | Schema, bounds, or unknown-parameter failures (for example, `r` or `p` out of range) | | 400 | `invalid_params` | Inputs pass validation but fail inside settlement simulation | -| 403 | `not_owner` | Machine belongs to another host | | 404 | `machine_not_found` | Invalid `machine_id` | | 429 | *(rate limited)* | Too many requests — retry with backoff. See [Rate Limits and Errors](/api-reference/rate-limits-and-errors). | diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index dec080af..1c04de3b 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -12,8 +12,12 @@ This page explains how SLA offers work from the host side — what you are promi SLA settlement is **lopsided by design**: when uptime is good, you keep the premium, but when uptime is bad, client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. You can optionally preview SLA economics before listing — use the [SLA backtester](/host/sla-backtester) (API, requires rental history) or the web console SLA preview (**Set Pricing → SLA**). The console preview works on first-time listings. + +Renters: see [Find and rent](/guides/instances/choosing/find-and-rent) and [Pricing](/guides/instances/pricing). SLA applies to **on-demand** rentals only — not interruptible or reserved/prepay. + + -When a client rents a machine with SLA enabled, they pay a small premium on top of the normal hourly rate. If uptime falls below the promised target, credits are applied to their account automatically. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. +When a client rents a machine with SLA enabled, they pay a small premium on top of the normal hourly rate (`dph_total` in search includes the SLA premium). If uptime falls below the promised target, credits are applied to their account automatically after **UTC daily settlement** — renters should check **Billing** the following UTC day. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. ## Choose your path @@ -78,7 +82,7 @@ When you list or update a machine, set SLA fields via the host console or `PUT / -**Confidence in one sentence:** The **preset name** (High / Normal / Wide) controls how **tight your claim spread** is around your target, which changes **client premiums** (tighter → lower premiums, wider → higher premiums). In the console, use the labeled presets rather than raw numbers. The ~83% figure describes how often your machine's actual uptime is expected to meet or exceed your claim — not a separate setting. +**Confidence in one sentence:** The **preset name** (High / Normal / Wide) controls how **tightly premiums are priced around the uptime level you claim you will deliver** (your claim), not around the published reliability target clients see in search. In the console, use the labeled presets rather than raw numbers. The ~83% figure describes how often your machine's actual uptime is expected to meet or exceed your claim — not a separate setting. ### Machine reliability score vs SLA uptime @@ -89,7 +93,9 @@ Do not assume the dashboard score equals SLA uptime. Use **Set Pricing → SLA** ### Confidence presets -If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults. A confidence of ~83% means you believe there is roughly an 83% chance your machine's actual uptime will meet or exceed your claim — higher confidence means lower client premiums. +**This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** + +If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults. At Normal confidence, historical modeling suggests roughly an ~83% chance your machine's measured uptime will meet or exceed your claim — higher confidence means lower client premiums. | Label | Approx. confidence | `sla_sigma_x` | Effect on premium | | --- | --- | --- | --- | @@ -181,20 +187,26 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ Set `end_date` so the offer does not stay open indefinitely — especially important for SLA commitments. See [Offer End Date](/host/hosting-overview#offer-end-date). -Minimal example (claim and confidence use defaults): +Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). + +Minimal example (includes recommended claim headroom): ```json { "machine": 12345, "price_gpu": 3.50, "end_date": 1735689600, - "sla_r_target": 0.95 + "sla_r_target": 0.95, + "sla_r_claim": 0.99, + "sla_sigma_x": 0.5 } ``` -Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). + +Setting only `sla_r_target` defaults `sla_r_claim` to the same value, which increases client premiums. For better economics, set **claim above target** (for example, target 95%, claim 99%). + -This creates an offer with target `0.95`, claim `0.95`, and confidence spread `0.5`. +This creates an offer with target `0.95`, claim `0.99`, and confidence spread `0.5`. Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. @@ -215,14 +227,15 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ #### Common errors -| Status | Code | When it happens | +| Status | Code / shape | When it happens | | --- | --- | --- | -| 401 | — | Missing or invalid Bearer token | -| 403 | `not_authorized` | API key lacks `machine_write` or other required permission | +| 401 | `success: false` + `msg` | Missing `machine_write` or other required permission | +| 403 | `machine_locked` | Machine is decommissioned or migration-locked | | 400 | `invalid_args` | Machine ID not found for your account (includes other hosts' machines) | | 400 | `invalid_sla_params` | SLA parameters failed validation | | 400 | `invalid_args` | Malformed or incompatible request body | -| 403 | `machine_locked` | Machine is decommissioned or migration-locked | + +**`machine_locked`:** Returned when a machine is decommissioned or migration-locked. If you are migrating hardware, finish or cancel active rentals first, remove or update the listing as needed, and contact support if the machine remains locked. Existing SLA terms on active contracts remain in force until those contracts end. **Success response (200):** @@ -264,7 +277,7 @@ This premium is what a client searching for 95% reliability would see added to t ### If you meet your claim -**You net** uses host earnings signs: positive = premium you kept; negative = payout you owed the client. +In the **You net** column, values follow host earnings sign conventions: positive means premium you kept; negative means payout you owed the client. | Measured uptime (simplified) | You net (per day) | | --- | --- | @@ -273,6 +286,16 @@ This premium is what a client searching for 95% reliability would see added to t You keep most or all of the premium. +### What if measured uptime is between my target and my claim? + +Example: you publish **target 95%**, claim **99%**, and measured uptime is **~97%**. + +- **Payouts** are evaluated against your published **target** (95%), not your claim. +- Because 97% is above 95%, you typically **owe no SLA payout** for that day. +- **Premiums** are priced from your **claim** (99%) and confidence — a higher claim generally means lower client premiums. + +**Claim** is mainly a pricing knob; **target** is what clients see and what drives payout eligibility. + ### If you miss the target @@ -283,7 +306,7 @@ Payouts scale relative to the day's compute revenue, not the premium collected. Visible client premiums are lower than backtester output when `sla_r_claim` is above `sla_r_target`. Use `worst_day_loss` as your worst single-day payout reference. The table below illustrates payout at the target boundary only. -These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Settlement uses a **blend of recent and historical uptime** (not just a single day's raw percentage), but the direction is the same — worse uptime means larger client payouts: +These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Payouts for brief outages may be **smaller than the worst-case table** shown below; exact settlement depends on measured uptime for the UTC day and active contract terms: | Measured uptime (simplified) | You net (per day) | | --- | --- | @@ -292,11 +315,7 @@ These scenarios show settlement when uptime **drops to or below** the target — To put the asymmetry in perspective: at ~$0.20/day in premiums, it takes roughly 210 good days to accumulate the $42 you could lose on a single day at the target boundary. The premium is a small fraction of daily compute, while the payout scales against total daily compute revenue. -On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged a premium on top of compute charges for periods when the instance was down. Your maximum SLA loss on any single settlement day is capped at that day's compute revenue, regardless of how the multi-window aggregation evaluates uptime. - - -Production settlement blends recent and historical uptime — not a single raw day — so short outages may not produce the maximum illustrated payout. - +On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged a premium on top of compute charges for periods when the instance was down. Your maximum SLA loss on any single settlement day is capped at that day's compute revenue. ## Risk scenarios @@ -340,10 +359,13 @@ After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal ### Console (recommended for day-to-day checks) -1. Open **Host → Billing** (or **Earnings** / **Reports**) for the machine and UTC date range. -2. Look for rows labeled **SLA premium** (client payments you keep) and **SLA payout** (amounts you owe after a miss). Exact menu names may vary; filter by machine ID and date if needed. -3. Settlement uses **UTC** calendar days — local-time downtime may appear on the adjacent UTC day. -4. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. +1. Go to **Host → Billing** (or **Earnings** / **Reports**). +2. Set the date range to include the UTC day you want to review. +3. Filter by machine ID if available. +4. Look for SLA line items — **positive** = premium you kept that day; **negative** = payout you owed the client. + +**If you don't see SLA rows:** widen the date range (settlement uses UTC day boundaries), confirm the machine had an active on-demand rental that day, and confirm SLA was enabled and the offer was **listed** (not just saved). +5. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. SLA daily settlement (premium kept / payout owed) does not currently emit host webhooks. Monitor via console billing or poll `machine-earnings`; settlements align to UTC calendar days. @@ -365,6 +387,8 @@ vastai show earnings --machine_id --start_date $(date -v-7d +%F) --end_date On Windows, use WSL or the API example below. See [`show earnings`](/cli/reference/show-earnings) for all options. +**Linux (GNU date) — parse SLA fields:** + ```bash vastai show earnings --machine_id --start_date $(date -d '7 days ago' +%F) --end_date $(date +%F) --raw \ | jq '.per_machine[] | {machine_id, sla_earn}' @@ -390,14 +414,10 @@ For API automation only — console users can stop after the Console subsection `GET /api/v0/users/{user_id}/machine-earnings/` returns SLA fields alongside compute earnings. Requires a **`billing_read`** API key (separate from `machine_read` used for the backtester). See [`show earnings`](/api-reference/billing/show-earnings). -This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request per second per IP; back off on HTTP 429. For day-level per-machine reconciliation at scale, prefer console billing reports over high-frequency API polling. +This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request every two seconds per IP (`threshold=2.0`); back off on HTTP 429. For day-level per-machine reconciliation at scale, prefer console billing reports over high-frequency API polling. -When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. - -There is no per-machine daily SLA series in this API. For day-level reconciliation on one machine, use the console earnings report. - -**Fleet operators:** There is no per-machine daily SLA series in the API. Use console day-level reports per machine for reconciliation, or poll `per_machine[].sla_earn` with `last_days=1` per `machid` (mind UTC day boundaries and rate limits). Expect ~N requests per poll cycle for N machines. +When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. There is no per-machine daily SLA series in this API; use console day-level reports per machine for reconciliation, or poll `per_machine[].sla_earn` with `last_days=1` per `machid` (mind UTC day boundaries and rate limits). Expect ~N requests per poll cycle for N machines. **Machine-scoped window total:** @@ -412,8 +432,8 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ | Field | Good day (meet target) | Bad day (miss target) | | --- | --- | --- | -| `per_machine[].sla_earn` / `summary.total_sla` | Positive (premium kept) | Negative (payout paid) | -| Fleet `per_day[].sla_earn` | Positive (premium kept) | Negative (payout paid) | +| `per_machine[].sla_earn` / `summary.total_sla` | Positive (premium kept) | Negative (payout you owe) | +| Fleet `per_day[].sla_earn` | Positive (premium kept) | Negative (payout you owe) | - `{user_id}` — Your account ID (from **Account → Profile** in the console, or `vastai show user`). - `sday` / `eday` — UTC day indices (days since 1970-01-01). Prefer `?last_days=N` on the API if you do not want to compute indices manually. From 72ad3fee6a82891e90ea51e94e3d4410fc9507aa Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:37:17 -0700 Subject: [PATCH 07/45] docs(sla): address doc-review consensus (cycle 5) Fix confidence preset percentages, console step numbering, economics tail-risk cap, fleet listing workflow, and backtester error table. Co-authored-by: Cursor --- host/hosting-overview.mdx | 2 +- host/sla-backtester.mdx | 24 ++++++++++++------------ host/sla-offers.mdx | 37 ++++++++++++++++++++++++++----------- 3 files changed, 39 insertions(+), 24 deletions(-) diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 2bd57fba..266503a1 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -45,7 +45,7 @@ The main offer parameters include: - the pricing for GPUs, internet, storage - the discount schedule param which determines the price difference between [on-demand](/guides/instances/rental-types) and [reserved](/guides/instances/rental-types) instances - the min bid price for [interruptible](/guides/instances/rental-types) instances -- the min_gpu param controlling 'slicing' (explained below) +- the min_gpu param controlling 'slicing' (explained below) — same concept as CLI `min_chunk` / `-m` - the offer end date, which determines how long the offer accepts new rental contracts - **SLA (optional):** Optional uptime coverage for on-demand rentals. Configure in **Set Pricing → SLA**, save pricing, then click **LIST** to publish the offer. SLA parameters are not yet available in the published CLI/SDK. See [Listing an SLA offer → Web console](/host/sla-offers#web-console). diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index b0c3915e..a05cfdec 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -28,12 +28,16 @@ See [Choose your path](#choose-your-path) below. ## When to use it -Use the backtester before you enable SLA on a listing, or when you want to tune parameters. The machine needs at least a few weeks of rental history. If `has_data` is `false`, widen the date range or pick a machine with more activity: +Use the backtester before you enable SLA on a listing, or when you want to tune parameters. The machine needs at least a few weeks of rental history. -- **Pick a reliability target** — see how often you would have kept premiums or paid them out on historical data -- **Compare confidence levels** — tighter confidence means lower premiums for clients but more risk to you if uptime slips -- **Stress-test bad weeks** — use the optional flat uptime override to see payout size if reliability dropped -- **Compare to history** — each day includes `historical_sla`, your machine's realized SLA earnings on that day (zero if you were not offering SLA) +If `has_data` is `false`, widen the date range or pick a machine with more rental activity. + +Use the backtester to: + +- Pick a reliability target and confidence before you enable SLA on a listing +- Compare how premium and worst-case payout change across targets +- Stress-test a lower reliability assumption before you commit +- Compare to history — each day includes `historical_sla`, your machine's realized SLA earnings on that day (zero if you were not offering SLA) For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). @@ -264,17 +268,13 @@ Higher confidence (higher `p`) → tighter spread → lower premiums for clients | HTTP | `error` / shape | Cause | | --- | --- | --- | -| 403 | `auth_error` | Authorization header missing or invalid session | -| 401 | `auth_error` | API key invalid | -| 401 | authorization `msg` | Valid key but missing `machine_read` (or other scope denial) | +| 400 | `invalid_range`, `range_too_large`, `bad_request`, `invalid_params` | Invalid query parameters or simulation failure | | 403 | `not_owner` | Machine belongs to another host | -| 400 | `invalid_range` | `start_date` is after `end_date` | -| 400 | `range_too_large` | More than 366 days requested | -| 400 | `bad_request` | Schema, bounds, or unknown-parameter failures (for example, `r` or `p` out of range) | -| 400 | `invalid_params` | Inputs pass validation but fail inside settlement simulation | | 404 | `machine_not_found` | Invalid `machine_id` | | 429 | *(rate limited)* | Too many requests — retry with backoff. See [Rate Limits and Errors](/api-reference/rate-limits-and-errors). | +For missing or invalid API keys and permission denials (`machine_read`), see [Authentication](/api-reference/authentication). + ## Recommended workflow 1. **Run a baseline backtest** on a machine with at least a few weeks of rental history: diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 1c04de3b..8b47dc17 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -82,7 +82,7 @@ When you list or update a machine, set SLA fields via the host console or `PUT / -**Confidence in one sentence:** The **preset name** (High / Normal / Wide) controls how **tightly premiums are priced around the uptime level you claim you will deliver** (your claim), not around the published reliability target clients see in search. In the console, use the labeled presets rather than raw numbers. The ~83% figure describes how often your machine's actual uptime is expected to meet or exceed your claim — not a separate setting. +**Confidence in one sentence:** The **preset name** (High / Normal / Wide) controls how **tightly premiums are priced around the uptime level you claim you will deliver** (your claim), not around the published reliability target clients see in search. In the console, use the labeled presets rather than raw numbers. The ~83% figure applies to the **High** preset — it describes how often your machine's actual uptime is expected to meet or exceed your claim, not the target percentage itself. ### Machine reliability score vs SLA uptime @@ -95,14 +95,16 @@ Do not assume the dashboard score equals SLA uptime. Use **Set Pricing → SLA** **This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** -If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults. At Normal confidence, historical modeling suggests roughly an ~83% chance your machine's measured uptime will meet or exceed your claim — higher confidence means lower client premiums. +If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults: -| Label | Approx. confidence | `sla_sigma_x` | Effect on premium | +| Label | Approx. chance uptime meets claim | `sla_sigma_x` | Effect on premium | | --- | --- | --- | --- | | High | ~83% | `0.2` | Lowest premiums — you are very sure about your claim | | Normal (default) | ~67% | `0.5` | Balanced default | | Wide | ~50% | `1.0` | Higher premiums — more uncertainty priced in | +Higher preset confidence (tighter spread) → lower client premiums, but less room for uptime to slip before payouts. + ### Validation rules Offers with invalid combinations are rejected at listing time: @@ -136,10 +138,11 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove ### Web console 1. Open your machine on the [Host Machines page](https://cloud.vast.ai/host/machines) → **Set Pricing**. -2. Expand **SLA**. -3. Set **Reliability target** (`sla_r_target`), **Reliability claim** (`sla_r_claim`), and **Confidence** (`sla_sigma_x` or a preset). -4. Save and confirm the SLA premium preview before listing. -5. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. +2. Set base listing fields first (GPU price, offer end date, rental types) if this is a new listing. +3. Expand **SLA**. +4. Set **Reliability target**, **Reliability claim**, and **Confidence** (or a preset). API field names: `sla_r_target`, `sla_r_claim`, `sla_sigma_x`. +5. Save and confirm the SLA premium preview before listing. +6. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. In the web console, **Set Pricing → Save** stores SLA settings; clicking **LIST** publishes the offer to search. `PUT /api/v0/machines/create_asks/` performs both steps in one request — it creates or updates the **live listing** (same as pressing **LIST** or running `vastai list machine`), not a save-only draft. @@ -211,7 +214,17 @@ This creates an offer with target `0.95`, claim `0.99`, and confidence spread `0 Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. -Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. For fleet automation, prefer read-modify-write: `vastai show machines` → merge → `PUT /api/v0/machines/create_asks/`. +Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. For fleet automation, prefer read-modify-write: `vastai show machines --raw` → merge → `PUT /api/v0/machines/create_asks/`. + +### Fleet listing workflow + +For multiple machines, loop sequentially — do not parallelize without backoff: + +1. `PUT /api/v0/machines/create_asks/` with `machine` plus SLA fields and required base pricing. +2. On `429`, sleep and retry with exponential backoff. +3. On `invalid_sla_params` or `machine_locked`, log the machine ID and continue or abort per your rollout policy. + +See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for a similar sequential pattern. **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -264,9 +277,11 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ | Item | Amount | | --- | --- | -| Daily compute (`C`) | ~$84/day ($3.50 × 24 hr) | +| Daily compute (`C`) | ~$84/day ($3.50 × 24 hr GPU only — simplified) | | SLA premium to client | ~**$0.008/hr** (~$0.20/day) | +SLA payouts are capped at that UTC day's total billable earnings — GPU, storage, and bandwidth combined — not GPU compute alone. The simplified example below uses GPU-only math for readability; treat `worst_day_loss` from the [SLA backtester](/host/sla-backtester) as the authoritative tail-risk figure before you list. + Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst single-day payout exposure (`worst_day_loss`), not exact client premiums. For authoritative client-visible premiums, use **Set Pricing → SLA** in the console or **`dph_total`** in search offers — not backtester `total_sla` when claim exceeds target. @@ -315,7 +330,7 @@ These scenarios show settlement when uptime **drops to or below** the target — To put the asymmetry in perspective: at ~$0.20/day in premiums, it takes roughly 210 good days to accumulate the $42 you could lose on a single day at the target boundary. The premium is a small fraction of daily compute, while the payout scales against total daily compute revenue. -On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged a premium on top of compute charges for periods when the instance was down. Your maximum SLA loss on any single settlement day is capped at that day's compute revenue. +On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged a premium on top of compute charges for periods when the instance was down. Your maximum SLA loss on any single settlement day is capped at that day's total billable earnings (GPU, storage, and bandwidth). ## Risk scenarios @@ -363,9 +378,9 @@ After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal 2. Set the date range to include the UTC day you want to review. 3. Filter by machine ID if available. 4. Look for SLA line items — **positive** = premium you kept that day; **negative** = payout you owed the client. +5. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. **If you don't see SLA rows:** widen the date range (settlement uses UTC day boundaries), confirm the machine had an active on-demand rental that day, and confirm SLA was enabled and the offer was **listed** (not just saved). -5. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. SLA daily settlement (premium kept / payout owed) does not currently emit host webhooks. Monitor via console billing or poll `machine-earnings`; settlements align to UTC calendar days. From ca4207934c4fbb82070f4dd43e6b7d50263a493f Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:42:18 -0700 Subject: [PATCH 08/45] docs(sla): address doc-review consensus (cycle 6) Clarify hourly vs daily premium framing, promote fleet listing section, fix setup URL consistency, and improve earnings API fleet guidance. Co-authored-by: Cursor --- host/hosting-overview.mdx | 4 ++-- host/sla-offers.mdx | 38 ++++++++++++++++++++++++++++---------- 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 266503a1..42a079fa 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -47,7 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) — same concept as CLI `min_chunk` / `-m` - the offer end date, which determines how long the offer accepts new rental contracts -- **SLA (optional):** Optional uptime coverage for on-demand rentals. Configure in **Set Pricing → SLA**, save pricing, then click **LIST** to publish the offer. SLA parameters are not yet available in the published CLI/SDK. See [Listing an SLA offer → Web console](/host/sla-offers#web-console). +- **SLA (optional):** Uptime coverage for on-demand rentals. Configure in **Set Pricing → SLA**, save pricing, then click **LIST** to publish. SLA can increase earnings on good days but expose you to large payouts on bad days — read [SLA Offers → Economics walkthrough](/host/sla-offers#economics-walkthrough) before enabling. SLA parameters are not yet available in the published CLI/SDK. See [Listing an SLA offer → Web console](/host/sla-offers#web-console). The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. @@ -255,7 +255,7 @@ To uninstall, use the Vast uninstall script located at https://s3.amazonaws.com/ ### How do I host my machine(s) on Vast? How can I rent my PC? -Hosting on Vast will require some Linux knowledge, as you will be maintaining a server. Our setup guide is [here](https://vast.ai/console/host/setup/). After the first paragraph of the guide there is a link to the hosting agreement. Once you agree, your account will be converted to a hosting account. You can review our [FAQ](https://vast.ai/faq/#Hosting-General) that answers many of your hosting questions. +Hosting on Vast will require some Linux knowledge, as you will be maintaining a server. Our setup guide is [here](https://cloud.vast.ai/host/setup/). After the first paragraph of the guide there is a link to the hosting agreement. Once you agree, your account will be converted to a hosting account. You can review our [FAQ](https://vast.ai/faq/#Hosting-General) that answers many of your hosting questions. ### How do I get an invoice? diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 8b47dc17..d668f615 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -4,7 +4,7 @@ description: "Offer reliability guarantees on your machines, set SLA parameters, "canonical": "/host/sla-offers" --- -Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is reliability insurance: the client pays a small daily premium, and if uptime falls short of the agreed target, the client receives a payout from your earnings. +Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is reliability insurance: the client pays a small hourly SLA add-on included in `dph_total`, and if uptime falls short of the agreed target, the client receives a payout from your earnings. This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. @@ -13,11 +13,11 @@ SLA settlement is **lopsided by design**: when uptime is good, you keep the prem -Renters: see [Find and rent](/guides/instances/choosing/find-and-rent) and [Pricing](/guides/instances/pricing). SLA applies to **on-demand** rentals only — not interruptible or reserved/prepay. +**Renters:** SLA coverage, premiums, and credits are not yet documented on our renter guides. Until a dedicated client SLA page ships, see [What your clients see](#what-your-clients-see) below for a brief summary. -When a client rents a machine with SLA enabled, they pay a small premium on top of the normal hourly rate (`dph_total` in search includes the SLA premium). If uptime falls below the promised target, credits are applied to their account automatically after **UTC daily settlement** — renters should check **Billing** the following UTC day. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. +Clients pay a small hourly SLA add-on included in `dph_total` (for example, ~$0.008/hr on top of the base GPU rate). Premiums and payouts are settled once per UTC calendar day — search and the console show the hourly rate; billing reconciles daily. If uptime falls below the promised target, credits are applied automatically after **UTC daily settlement**. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. ## Choose your path @@ -53,8 +53,8 @@ Think of an SLA offer as three linked ideas: When a client rents with SLA enabled: -- They pay **compute** (GPU, storage, bandwidth) plus a **daily SLA premium**. -- Each day, Vast measures how long the instance was online and settles the SLA. +- They pay **compute** (GPU, storage, bandwidth) plus a **small hourly SLA add-on** included in `dph_total`. +- Each UTC calendar day, Vast measures how long the instance was online and settles the SLA. - **Good uptime** → you keep the premium for that day. - **Bad uptime** → you pay the client from your earnings (up to the day's compute revenue). @@ -188,7 +188,7 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ }' ``` -Set `end_date` so the offer does not stay open indefinitely — especially important for SLA commitments. See [Offer End Date](/host/hosting-overview#offer-end-date). +Set `end_date` so the offer does not stay open indefinitely — especially important for SLA commitments. See [Offer End Date](/host/hosting-overview#offer-end-date). Convert a calendar date to Unix seconds: `date -u -d '2025-01-01' +%s` (Linux) or `date -u -j -f '%Y-%m-%d' '2025-01-01' +%s` (macOS). The CLI also accepts `MM/DD/YYYY` via `-e`. Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). @@ -214,7 +214,14 @@ This creates an offer with target `0.95`, claim `0.99`, and confidence spread `0 Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. -Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. For fleet automation, prefer read-modify-write: `vastai show machines --raw` → merge → `PUT /api/v0/machines/create_asks/`. +Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. For fleet automation, read current settings then merge: + +```bash +vastai show machines --raw | jq '.[] | select(.id==12345) | {id, sla_r_target, sla_r_claim, sla_sigma_x, price_gpu, end_date}' +``` + +Then `PUT /api/v0/machines/create_asks/` with merged fields. + ### Fleet listing workflow @@ -225,7 +232,6 @@ For multiple machines, loop sequentially — do not parallelize without backoff: 3. On `invalid_sla_params` or `machine_locked`, log the machine ID and continue or abort per your rollout policy. See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for a similar sequential pattern. - **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -278,7 +284,7 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ | Item | Amount | | --- | --- | | Daily compute (`C`) | ~$84/day ($3.50 × 24 hr GPU only — simplified) | -| SLA premium to client | ~**$0.008/hr** (~$0.20/day) | +| SLA premium (client pays) | ~**$0.008/hr** (~$0.20/day at 24 hr) | SLA payouts are capped at that UTC day's total billable earnings — GPU, storage, and bandwidth combined — not GPU compute alone. The simplified example below uses GPU-only math for readability; treat `worst_day_loss` from the [SLA backtester](/host/sla-backtester) as the authoritative tail-risk figure before you list. @@ -432,7 +438,19 @@ For API automation only — console users can stop after the Console subsection This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request every two seconds per IP (`threshold=2.0`); back off on HTTP 429. For day-level per-machine reconciliation at scale, prefer console billing reports over high-frequency API polling. -When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. There is no per-machine daily SLA series in this API; use console day-level reports per machine for reconciliation, or poll `per_machine[].sla_earn` with `last_days=1` per `machid` (mind UTC day boundaries and rate limits). Expect ~N requests per poll cycle for N machines. +When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. + +**Quick rules:** +- **One machine:** use `per_machine[].sla_earn` with `machid` set. +- **Fleet:** one request without `machid` returns all machines in `per_machine[]`: + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/users/{user_id}/machine-earnings/?last_days=1" \ + | jq '.per_machine[] | {machine_id, sla_earn}' +``` + +Poll no faster than about one request every two seconds. Prefer console billing exports for month-end reconciliation. **Machine-scoped window total:** From d8129fed327e03da7ed03816fcf5f2571dc56ede Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:46:45 -0700 Subject: [PATCH 09/45] docs(sla): address doc-review consensus (cycle 7) Fix show machines jq path for partial updates, define dph_total early, and correct backtester economics walkthrough link. Co-authored-by: Cursor --- host/sla-backtester.mdx | 2 +- host/sla-offers.mdx | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index a05cfdec..3593ed01 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -15,7 +15,7 @@ It replays your machine's **real historical compute earnings and uptime** throug See [Choose your path](#choose-your-path) below. -**Don't want to use the API?** The backtester is optional. Use the web console SLA preview and the economics walkthrough on [SLA Offers](/host/sla-offers#listing-an-sla-offer) to evaluate SLA before listing. The backtester is for hosts who want historical replay via the API. +**Don't want to use the API?** The backtester is optional. Use the web console SLA preview and the [economics walkthrough](/host/sla-offers#economics-walkthrough) on SLA Offers to evaluate SLA before listing. The backtester is for hosts who want historical replay via the API. ## Choose your path diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index d668f615..aff58df8 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -4,7 +4,7 @@ description: "Offer reliability guarantees on your machines, set SLA parameters, "canonical": "/host/sla-offers" --- -Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is reliability insurance: the client pays a small hourly SLA add-on included in `dph_total`, and if uptime falls short of the agreed target, the client receives a payout from your earnings. +Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is reliability insurance: the client pays a small hourly SLA add-on included in **`dph_total`** (dollars per hour total in search — base compute plus SLA premium), and if uptime falls short of the agreed target, the client receives a payout from your earnings. This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. @@ -214,12 +214,14 @@ This creates an offer with target `0.95`, claim `0.99`, and confidence spread `0 Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. -Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. For fleet automation, read current settings then merge: +Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. Before merging partial SLA updates, read current listing fields from `vastai show machine --raw` (or the machine detail API) and confirm the response includes `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, `price_gpu`, and `end_date`: ```bash -vastai show machines --raw | jq '.[] | select(.id==12345) | {id, sla_r_target, sla_r_claim, sla_sigma_x, price_gpu, end_date}' +vastai show machines --raw | jq '.machines[] | select(.id == 12345 or .id == "12345") | {id, sla_r_target, sla_r_claim, sla_sigma_x, price_gpu, end_date}' ``` +Machine `id` may be a string in raw JSON. The response is wrapped in a `machines` array. If SLA fields are missing, use `vastai show machine 12345 --raw` instead. + Then `PUT /api/v0/machines/create_asks/` with merged fields. From 932a1d58bfc97f850de4da0223c8fd8dd545011b Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:54:41 -0700 Subject: [PATCH 10/45] docs(sla): address doc-review consensus (cycle 8) Extend show-machines OpenAPI for SLA read path, add search field mapping, fix daily vs window monitoring examples, uptime measurement, and hosting fixes. Co-authored-by: Cursor --- api-reference/openapi.yaml | 34 ++++++ api-reference/openapi/yaml/show_machines.yaml | 30 +++++ host/hosting-overview.mdx | 22 ++-- host/sla-backtester.mdx | 8 +- host/sla-offers.mdx | 103 ++++++++++++++---- 5 files changed, 161 insertions(+), 36 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 2cedda7f..d2d3d54b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -8804,6 +8804,12 @@ paths: user. + The `--raw` CLI output includes listing and SLA fields (`price_gpu`, `end_date`, + `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, etc.) used for read-modify-write + before partial SLA updates. See SLA Offers partial-update workflow in host + documentation. + + CLI Usage: `vastai show machines [--user_id ]`' operationId: getMachines parameters: @@ -8832,6 +8838,34 @@ paths: name: type: string description: The name of the machine. + price_gpu: + type: number + description: GPU rental price in $/hour (when present in raw listing output). + end_date: + type: number + description: Offer expiration as Unix timestamp (when present in raw listing output). + min_chunk: + type: integer + description: Minimum GPUs rented together (GPU slicing). + sla_r_target: + type: number + description: SLA reliability target (0 to disable; greater than 0 and at most 0.9999 when enabled). + sla_r_claim: + type: number + description: SLA reliability claim (must be greater than or equal to target). + sla_sigma_x: + type: number + description: SLA confidence spread (maps to console High / Normal / Wide presets). + example: + machines: + - id: '12345' + name: my-h100 + price_gpu: 3.5 + end_date: 1735689600 + min_chunk: 1 + sla_r_target: 0.95 + sla_r_claim: 0.99 + sla_sigma_x: 0.5 '401': description: Unauthorized - User authentication failed '429': diff --git a/api-reference/openapi/yaml/show_machines.yaml b/api-reference/openapi/yaml/show_machines.yaml index 4e5c4420..049d370b 100644 --- a/api-reference/openapi/yaml/show_machines.yaml +++ b/api-reference/openapi/yaml/show_machines.yaml @@ -9,6 +9,8 @@ paths: description: | Fetches data for multiple machines associated with the authenticated user. + The `--raw` CLI output includes listing and SLA fields (`price_gpu`, `end_date`, `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, etc.) used for read-modify-write before partial SLA updates. See [SLA Offers — Partial updates](/host/sla-offers#api-for-automation). + CLI Usage: `vastai show machines [--user_id ]` operationId: getMachines parameters: @@ -37,6 +39,34 @@ paths: name: type: string description: The name of the machine. + price_gpu: + type: number + description: GPU rental price in $/hour (when present in raw listing output). + end_date: + type: number + description: Offer expiration as Unix timestamp (when present in raw listing output). + min_chunk: + type: integer + description: Minimum GPUs rented together (GPU slicing). + sla_r_target: + type: number + description: SLA reliability target (0 to disable; greater than 0 and at most 0.9999 when enabled). + sla_r_claim: + type: number + description: SLA reliability claim (must be greater than or equal to target). + sla_sigma_x: + type: number + description: SLA confidence spread (maps to console High / Normal / Wide presets). + example: + machines: + - id: "12345" + name: my-h100 + price_gpu: 3.5 + end_date: 1735689600 + min_chunk: 1 + sla_r_target: 0.95 + sla_r_claim: 0.99 + sla_sigma_x: 0.5 '401': description: Unauthorized - User authentication failed '429': diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 42a079fa..f779ab20 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -16,7 +16,7 @@ Vast is a GPU marketplace. Hosts sell GPU resources on the marketplace. Hosts ar ## Account setup and hosting agreement -You must create a new account for hosting. If you are using Vast.ai as a client, do not use the same account. A single client and hosting account is not supported and you will quickly run into issues. +You must create a new account for hosting. If you are using Vast.ai as a client, do not use the same account. Using the same account for both client and hosting is not supported and you will quickly run into issues. Once your account is created, open the [host setup guide](https://cloud.vast.ai/host/setup/). There is a link in the first paragraph to the hosting agreement. Read through the agreement. Once you accept, your account will then be converted to a hosting account. You will notice there is now a link to Machines in the navigation, along with some other changes. Your account can now list machines that are running the daemon software. @@ -47,7 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) — same concept as CLI `min_chunk` / `-m` - the offer end date, which determines how long the offer accepts new rental contracts -- **SLA (optional):** Uptime coverage for on-demand rentals. Configure in **Set Pricing → SLA**, save pricing, then click **LIST** to publish. SLA can increase earnings on good days but expose you to large payouts on bad days — read [SLA Offers → Economics walkthrough](/host/sla-offers#economics-walkthrough) before enabling. SLA parameters are not yet available in the published CLI/SDK. See [Listing an SLA offer → Web console](/host/sla-offers#web-console). +- **SLA (optional):** Optional uptime guarantee for on-demand rentals — clients pay a small premium; you may owe payouts if uptime misses your published target. You can list without SLA. See [SLA Offers](/host/sla-offers#economics-walkthrough) before enabling. The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. @@ -141,15 +141,15 @@ In addition to GPU offers, hosts can create volume offers on machines. A volume Allocated storage (that is, storage in use by client rental contracts) is subtracted from the total storage available on a machine, and split up proportionally among the machine's GPUs in remaining GPU offers. -For example, on a machine with 1000Gb of disk available and 2 GPUs, a host can create a volume offer of up to 1000 Gb. +For example, on a machine with 1000 GB of disk available and 2 GPUs, a host can create a volume offer of up to 1000 GB. -If they create a volume offer of 500 Gb, and it is not rented, the machine will be available for rent with 2 offers of 1xGPU 500Gb and 1 offer of 2xGPU 1000Gb. +If they create a volume offer of 500 GB, and it is not rented, the machine will be available for rent with 2 offers of 1xGPU 500 GB and 1 offer of 2xGPU 1000 GB. -If 200 Gb of the volume offer are rented, the GPU offers will reduce to 2 1xGPU 400Gb offers and 1 2xGPU 800Gb offer. The volume offer will still remain, as there is still available space, and update to offer 300Gb. +If 200 GB of the volume offer are rented, the GPU offers will reduce to 2 1xGPU 400 GB offers and 1 2xGPU 800 GB offer. The volume offer will still remain, as there is still available space, and update to offer 300 GB. -Similarly, if stored instances on the machine are taking up 800Gb, the volume offer will reduce to 200Gb. +Similarly, if stored instances on the machine are taking up 800 GB, the volume offer will reduce to 200 GB. -If stored instances are only taking up 400 Gb, the volume offer will not update, as there is still enough space on the machine to cover the volume offer. +If stored instances are only taking up 400 GB, the volume offer will not update, as there is still enough space on the machine to cover the volume offer. ### Listing Volumes @@ -168,7 +168,7 @@ vastai list volume -s -p ``` - Volume offer end dates **must** align with GPU offer end dates. Setting an end date on a volume will not update if there is an existing GPU offer. Setting a GPU offer end date will update volume offer end dates. + Volume offer end dates **must** align with GPU offer end dates. Setting an end date on a volume will not update the GPU offer's end date if a GPU offer already exists. Setting a GPU offer end date will update volume offer end dates. Volume offers will be unlisted when the machine is unlisted. They can additionally be unlisted with the command: @@ -222,9 +222,11 @@ Replace 12345 with your actual machine ID in question. You can see the number of Take the ID number from the first column and use that to create a free instance on your own machine. This example loads the latest pytorch image along with both jupyter and ssh direct launch modes. ```text Text -./vastai create instance --image pytorch/pytorch:latest --jupyter --direct --env '-e TZ=PDT -p 22:22 -p 8080:8080' +vastai create instance --image pytorch/pytorch:latest --jupyter --direct --env '-e TZ=PDT -p 22:22 -p 8080:8080' ``` +Use `./vastai` instead of `vastai` when running from the install directory. + You can then look at your [instance tab](https://cloud.vast.ai/instances/) to make sure that pytorch loaded correctly along with jupyter and ssh. Click on the \<\_ button to get the ssh command to connect to the instance. Test the direct ssh command. Click on the open button to test jupyter. If the button is stuck "connecting" then there is most likely a problem with the port configuration on the router in front of the machine. Once finished, destroy the instance. ## Maintenance @@ -309,7 +311,7 @@ To get an understanding of prices, check our [Market Stats page](https://cloud.v ### Why did the reliability on my machine decrease? -If the machine loses connection or if there is a client instance that does not want to start the machine's reliability will drop. +If the machine loses connection, or if a client instance fails to start, the machine's reliability will drop. ### How do I minimize my reliability dropping? diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 3593ed01..84df6947 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -223,7 +223,7 @@ Review `sla` day by day in `daily_results` to see which days would have helped o | `total_sla` | Net simulated SLA earnings. Positive = SLA would have added income overall | | `total_earnings` | Compute + simulated SLA | | `total_historical_sla` | Sum of realized historical SLA in the range | -| `worst_day_loss` | Largest single-day client payout (your worst simulated loss) | +| `worst_day_loss` | Largest single-day client payout (your worst simulated loss). Always a non-negative dollar amount — unlike signed `sla` / `sla_earn` fields | | `reserve` | Reserved for future use — ignore in production decisions today. | ## Interpreting results @@ -300,7 +300,7 @@ export VAST_API_KEY="YOUR_API_KEY" ```bash for id in $(vastai show machines -q); do - resp=$(curl -sf -H "Authorization: Bearer $VAST_API_KEY" \ + resp=$(curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=$id&r=0.95&p=0.6667" \ || echo '{"error":"request_failed"}') if echo "$resp" | jq -e '.error' >/dev/null 2>&1; then @@ -308,11 +308,11 @@ for id in $(vastai show machines -q); do else echo "$resp" | jq '{machine_id: '"$id"', worst_day_loss: .summary.worst_day_loss, total_sla: .summary.total_sla, has_data: .has_data}' fi - sleep 1 + sleep 2 done ``` -Use a `machine_read` key scoped to the machines you own. On `429`, back off per [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Parallel requests are not recommended unless you implement backoff. +Expect roughly two seconds per machine minimum (`sleep 2` plus request time). For 50 machines, budget at least a few minutes. Run off-peak before a fleet SLA rollout. On `429`, back off per [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Parallel requests are not recommended unless you implement backoff. 3. Compare `worst_day_loss` and `total_sla` across machines. 4. Apply `sla_r_claim` headroom when listing via the API (see [SLA Offers](/host/sla-offers#api-for-automation)). diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index aff58df8..5a4bbc8d 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -13,11 +13,11 @@ SLA settlement is **lopsided by design**: when uptime is good, you keep the prem -**Renters:** SLA coverage, premiums, and credits are not yet documented on our renter guides. Until a dedicated client SLA page ships, see [What your clients see](#what-your-clients-see) below for a brief summary. +**Clients:** see [What your clients see](#what-your-clients-see) below for how SLA appears in search and billing. -Clients pay a small hourly SLA add-on included in `dph_total` (for example, ~$0.008/hr on top of the base GPU rate). Premiums and payouts are settled once per UTC calendar day — search and the console show the hourly rate; billing reconciles daily. If uptime falls below the promised target, credits are applied automatically after **UTC daily settlement**. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. +Clients pay a small hourly SLA add-on included in `dph_total` (for example, ~$0.008/hr on top of the base GPU rate). On SLA-listed on-demand offers, coverage is included automatically when the client rents — no separate host-side toggle at rent time. The published **target %** appears in search and the rent flow alongside `dph_total`. Premiums and payouts settle once per UTC calendar day; credits typically post to **Billing** within a few hours after UTC midnight (exact timing can vary). If uptime falls below the promised target, credits are applied automatically. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. ## Choose your path @@ -26,6 +26,7 @@ Clients pay a small hourly SLA add-on included in `dph_total` (for example, ~$0. | --- | --- | | Preview economics and enable SLA in the console | [How it works](#how-it-works-plain-english) → [Listing an SLA offer](#listing-an-sla-offer) | | Enable or update SLA via API | [Before you enable SLA](#before-you-enable-sla) → [API (for automation)](#api-for-automation) | +| I list with CLI only (no SLA flags yet) | **Set Pricing → SLA** + **LIST** in the console, or REST `PUT /api/v0/machines/create_asks/` — SLA flags are **not** in `vastai list machine` yet | | Monitor payouts after listing | [Monitoring SLA after listing](#monitoring-sla-after-listing) | ## Before you enable SLA @@ -37,7 +38,7 @@ Before enabling SLA, finish normal listing setup: test your machine, set GPU pri SLA can be enabled on a first-time listing, but you still need base listing fields (GPU price, offer end date, etc.). See [Listing an SLA offer](#listing-an-sla-offer) and [Offer End Date](/host/hosting-overview#offer-end-date). -**Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. +**Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. Interruptible instances on an SLA-enabled machine are not SLA-covered; on-demand contracts on the same machine are. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. - Optional: run the [backtester](/host/sla-backtester) after you have weeks of history; otherwise use the web console SLA preview and the economics walkthrough on this page. @@ -58,7 +59,18 @@ When a client rents with SLA enabled: - **Good uptime** → you keep the premium for that day. - **Bad uptime** → you pay the client from your earnings (up to the day's compute revenue). -Under honest pricing, a host who delivers what they claim should roughly break even on SLA over time — premiums and payouts balance. +Over many good-uptime days, premiums can offset occasional payouts, but a single bad day can exceed months of collected premiums — see [Risk scenarios](#risk-scenarios) and `worst_day_loss` before you commit. + +### How uptime is measured + +SLA uptime is measured at the **rental contract (instance) level** using platform health signals for active on-demand contracts — not your personal SSH session or Jupyter tab. + +- **Instance fails to start** when a client rents → counts against SLA uptime for that contract. +- **Machine-level outage** while contracts are active → affects settlement for those contracts. +- **Brief host reboots** during active rentals may count as downtime depending on duration. +- **Scheduled maintenance** may receive credit case by case — see [Scheduled maintenance](#scheduled-maintenance). + +On sliced machines, SLA settles **per rental contract**. If one GPU slice fails but others remain healthy, only contracts on the affected slice are measured for downtime. ## SLA parameters @@ -89,15 +101,19 @@ When you list or update a machine, set SLA fields via the host console or `PUT / The **reliability score** on the Host Machines page reflects connection and instance-start behavior (and is earnings-weighted). **SLA settlement** measures whether covered instances met your published uptime target for billing purposes. -Do not assume the dashboard score equals SLA uptime. Use **Set Pricing → SLA** in the console or the backtester on historical data to choose `sla_r_target`, `sla_r_claim`, and confidence — not the Machines-page number alone. +Do not assume the dashboard score equals SLA uptime. Before choosing `sla_r_target`: + +1. Open **Host → Machines** → **Set Pricing → SLA** and review the console premium preview at candidate targets. +2. If you have rental history, run the [backtester](/host/sla-backtester) and check top-level `reliability` in the response. +3. Set **target** at or slightly below the uptime level you can sustain; use **claim above target** for competitive premiums. ### Confidence presets -**This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** +**This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** Use the **High / Normal / Wide** presets in the console UI; only set raw `sla_sigma_x` via API after you have saved once in the console. -If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults: +If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults. The probability column below describes **pricing preset tightness**, not a guarantee that uptime will meet your claim: -| Label | Approx. chance uptime meets claim | `sla_sigma_x` | Effect on premium | +| Label | Pricing preset meaning | `sla_sigma_x` | Effect on premium | | --- | --- | --- | --- | | High | ~83% | `0.2` | Lowest premiums — you are very sure about your claim | | Normal (default) | ~67% | `0.5` | Balanced default | @@ -140,7 +156,7 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove 1. Open your machine on the [Host Machines page](https://cloud.vast.ai/host/machines) → **Set Pricing**. 2. Set base listing fields first (GPU price, offer end date, rental types) if this is a new listing. 3. Expand **SLA**. -4. Set **Reliability target**, **Reliability claim**, and **Confidence** (or a preset). API field names: `sla_r_target`, `sla_r_claim`, `sla_sigma_x`. +4. Set **Reliability target**, **Reliability claim**, and **Confidence** (or a preset). 5. Save and confirm the SLA premium preview before listing. 6. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. @@ -174,6 +190,10 @@ Before you call this endpoint, your machine must appear on **Host → Machines** Listing or updating SLA parameters requires an API key with **`machine_write`** permission. Backtesting requires **`machine_read`**. See [API permissions](/api-reference/permissions). + +The example below **adds SLA to an offer that already has base pricing configured**. For a first-time listing, include all required base fields (`price_gpu`, `end_date`, `min_chunk`, storage/bandwidth prices as needed) — see [Hosting overview](/host/hosting-overview#offers-and-rental-contracts). + + ```bash curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -H "Authorization: Bearer YOUR_API_KEY" \ @@ -235,6 +255,20 @@ For multiple machines, loop sequentially — do not parallelize without backoff: See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for a similar sequential pattern. +```bash +export VAST_API_KEY="YOUR_API_KEY" +for id in $(vastai show machines -q); do + current=$(vastai show machine "$id" --raw) + curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ + -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -d "$(echo "$current" | jq -c '{machine: (.id|tonumber), price_gpu, end_date, sla_r_target: 0.95, sla_r_claim: 0.99, sla_sigma_x: 0.5}')" + sleep 2 +done +``` + +Log `invalid_sla_params` and `machine_locked` responses; back off on HTTP 429. + **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: ```bash @@ -250,7 +284,7 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ | Status | Code / shape | When it happens | | --- | --- | --- | -| 401 | `success: false` + `msg` | Missing `machine_write` or other required permission | +| 401 | `success: false` + `msg` (+ optional `error`) | Missing `machine_write` or other required permission | | 403 | `machine_locked` | Machine is decommissioned or migration-locked | | 400 | `invalid_args` | Machine ID not found for your account (includes other hosts' machines) | | 400 | `invalid_sla_params` | SLA parameters failed validation | @@ -298,6 +332,22 @@ The economics above assume **claim above target** (headroom): claim (99%) is abo This premium is what a client searching for 95% reliability would see added to the total hourly price in search results (`dph_total` — visible in the console SLA preview or [Search Offers](/api-reference/search/search-offers) results). +### Search / client-visible fields + +When SLA is enabled on an offer, clients see: + +- **`dph_total`** — total $/hour including the SLA premium (authoritative for client-visible all-in pricing). +- **`expected_reliability`** — the advertised SLA target (maps to your `sla_r_target`). +- **`reliability` / `reliability2`** — historical machine reliability scores, **not** your SLA target. + +Verify after listing: + +```bash +vastai search offers 'machine_id=12345' --raw | jq '.[0] | {dph_total, price_gpu, expected_reliability, reliability}' +``` + +Premium sizing uses internal SLA math — use the console preview or `dph_total` above, not backtester `total_sla`, when claim exceeds target. + ### If you meet your claim In the **You net** column, values follow host earnings sign conventions: positive means premium you kept; negative means payout you owed the client. @@ -378,14 +428,14 @@ Use the [SLA Earnings Backtester](/host/sla-backtester) (API-only; requires a `m ## Monitoring SLA after listing -After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal Time) day boundaries. +After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal Time) day boundaries. SLA earnings rows typically appear in **Host → Billing** within a few hours after UTC midnight (exact timing can vary). ### Console (recommended for day-to-day checks) 1. Go to **Host → Billing** (or **Earnings** / **Reports**). 2. Set the date range to include the UTC day you want to review. 3. Filter by machine ID if available. -4. Look for SLA line items — **positive** = premium you kept that day; **negative** = payout you owed the client. +4. Look for **SLA** entries in the earnings breakdown — positive amounts are premiums you kept; negative amounts are payouts you owed the client. 5. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. **If you don't see SLA rows:** widen the date range (settlement uses UTC day boundaries), confirm the machine had an active on-demand rental that day, and confirm SLA was enabled and the offer was **listed** (not just saved). @@ -410,14 +460,21 @@ vastai show earnings --machine_id --start_date $(date -v-7d +%F) --end_date On Windows, use WSL or the API example below. See [`show earnings`](/cli/reference/show-earnings) for all options. -**Linux (GNU date) — parse SLA fields:** +**Linux (GNU date) — one UTC day (compare to `worst_day_loss`):** + +```bash +vastai show earnings --machine_id --start_date $(date -u -d 'yesterday' +%F) --end_date $(date -u -d 'yesterday' +%F) --raw \ + | jq '.per_machine[] | select(.machine_id == or .machine_id == "") | {machine_id, sla_earn}' +``` + +**Linux (GNU date) — seven-day window (do not compare directly to single-day `worst_day_loss`):** ```bash vastai show earnings --machine_id --start_date $(date -d '7 days ago' +%F) --end_date $(date +%F) --raw \ - | jq '.per_machine[] | {machine_id, sla_earn}' + | jq '.per_machine[] | select(.machine_id == or .machine_id == "") | {machine_id, sla_earn}' ``` -Positive `sla_earn` = net SLA premium you kept that period; negative = net payout you owe. See the sign-convention table in the API subsection below. +Positive `sla_earn` = net SLA premium you kept that period; negative = net payout you owe. Weekly aggregates are window totals, not daily series — use a one-day range above for day-level checks. ### API (automation) @@ -443,8 +500,8 @@ This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/ra When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. **Quick rules:** -- **One machine:** use `per_machine[].sla_earn` with `machid` set. -- **Fleet:** one request without `machid` returns all machines in `per_machine[]`: +- **One machine, one UTC day:** use `last_days=1` with `machid` set (or a one-day `start_date`/`end_date` range). There is no per-machine daily SLA series in the API — day-level breakdown for a single machine is easiest in **Host → Billing**. +- **Fleet snapshot:** one request without `machid` returns all machines in `per_machine[]` for the window: ```bash curl -s -H "Authorization: Bearer $VAST_API_KEY" \ @@ -455,14 +512,16 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ Poll no faster than about one request every two seconds. Prefer console billing exports for month-end reconciliation. -**Machine-scoped window total:** +**Machine-scoped one-day total:** ```bash curl -s -H "Authorization: Bearer $VAST_API_KEY" \ - "https://console.vast.ai/api/v0/users/{user_id}/machine-earnings/?machid=12345&last_days=7" \ - | jq '.per_machine[] | select(.machine_id==12345) | {machine_id, sla_earn}' + "https://console.vast.ai/api/v0/users/{user_id}/machine-earnings/?machid=12345&last_days=1" \ + | jq '.per_machine[] | select(.machine_id == 12345 or .machine_id == "12345") | {machine_id, sla_earn}' ``` +Do **not** compare `last_days=7` totals to single-day `worst_day_loss` from the backtester. + **Sign convention** (same as backtester `sla` / `historical_sla`): | Field | Good day (meet target) | Bad day (miss target) | @@ -472,9 +531,9 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ - `{user_id}` — Your account ID (from **Account → Profile** in the console, or `vastai show user`). - `sday` / `eday` — UTC day indices (days since 1970-01-01). Prefer `?last_days=N` on the API if you do not want to compute indices manually. -- Settlement is evaluated on UTC day boundaries. +- Settlement is evaluated on UTC day boundaries. Rows typically update within a few hours after UTC midnight. -The backtester's `historical_sla` replays past settlement and is not a live billing feed. For fleet-scale day-by-day review per machine, use the console or poll `per_machine[].sla_earn` over rolling windows. +The backtester's `historical_sla` replays past settlement and is not a live billing feed. For day-level per-machine reconciliation, use **Host → Billing**; use `last_days=1` API polling only when you need automation. ## Tips for competitive SLA offers From 37a7494a720d660eb2d99265cc37c8d4dbc6285c Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 20:59:52 -0700 Subject: [PATCH 11/45] docs(sla): address doc-review consensus (cycle 9) Fix SLA opt-in phrasing, fleet listing read-modify-write pattern, UTC monitoring dates, and confidence preset wording. Co-authored-by: Cursor --- host/sla-offers.mdx | 20 +++++++++++--------- snippets/host/cli/list-machine.mdx | 2 +- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 5a4bbc8d..f25fe3a2 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -52,7 +52,7 @@ Think of an SLA offer as three linked ideas: 2. **Your reliability claim** — what you believe your machine will actually deliver. 3. **Your confidence** — how sure you are about that claim. Tight confidence means you stand behind a narrow range; wide confidence means a wider defensible range and clients pay a higher premium. -When a client rents with SLA enabled: +When a client rents an on-demand instance on your SLA-listed offer, Vast measures uptime against your published target and claim percentages: - They pay **compute** (GPU, storage, bandwidth) plus a **small hourly SLA add-on** included in `dph_total`. - Each UTC calendar day, Vast measures how long the instance was online and settles the SLA. @@ -111,7 +111,7 @@ Do not assume the dashboard score equals SLA uptime. Before choosing `sla_r_targ **This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** Use the **High / Normal / Wide** presets in the console UI; only set raw `sla_sigma_x` via API after you have saved once in the console. -If you prefer to think in terms of confidence rather than `sla_sigma_x`, these presets match the shipped defaults. The probability column below describes **pricing preset tightness**, not a guarantee that uptime will meet your claim: +The **Pricing preset meaning** column below describes what each confidence setting implies for premium sizing — not your uptime target. These presets control pricing spread; the ~83%, ~67%, and ~50% figures describe statistical pricing confidence, not guaranteed uptime: | Label | Pricing preset meaning | `sla_sigma_x` | Effect on premium | | --- | --- | --- | --- | @@ -234,13 +234,13 @@ This creates an offer with target `0.95`, claim `0.99`, and confidence spread `0 Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. -Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. Before merging partial SLA updates, read current listing fields from `vastai show machine --raw` (or the machine detail API) and confirm the response includes `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, `price_gpu`, and `end_date`: +Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. Read current listing fields from `vastai show machines --raw` (filter with `jq` below). See [Show Machines](/api-reference/machines/show-machines) for the documented REST response shape: ```bash vastai show machines --raw | jq '.machines[] | select(.id == 12345 or .id == "12345") | {id, sla_r_target, sla_r_claim, sla_sigma_x, price_gpu, end_date}' ``` -Machine `id` may be a string in raw JSON. The response is wrapped in a `machines` array. If SLA fields are missing, use `vastai show machine 12345 --raw` instead. +Machine `id` may be a string in raw JSON. The response is wrapped in a `machines` array. Then `PUT /api/v0/machines/create_asks/` with merged fields. @@ -258,16 +258,18 @@ See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for ```bash export VAST_API_KEY="YOUR_API_KEY" for id in $(vastai show machines -q); do - current=$(vastai show machine "$id" --raw) - curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ + body=$(vastai show machines --raw | jq -c --arg id "$id" \ + '.machines[] | select((.id|tostring) == $id) | {machine: (.id|tonumber), price_gpu, end_date, min_chunk, sla_r_target: 0.95, sla_r_claim: 0.99, sla_sigma_x: 0.5}') + resp=$(curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -H "Authorization: Bearer $VAST_API_KEY" \ -H "Content-Type: application/json" \ - -d "$(echo "$current" | jq -c '{machine: (.id|tonumber), price_gpu, end_date, sla_r_target: 0.95, sla_r_claim: 0.99, sla_sigma_x: 0.5}')" + -d "$body") + echo "machine_id=$id response: $resp" sleep 2 done ``` -Log `invalid_sla_params` and `machine_locked` responses; back off on HTTP 429. +Check each response for `success`, `invalid_sla_params`, and `machine_locked` before continuing. Back off on HTTP 429. **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -402,7 +404,7 @@ Clients receive payouts tied to how far measured uptime falls below the target. ### You set target equal to claim (for example, both 95%) -Premiums are **much higher** because you are not offering any headroom below your claim. Clients only buy this when they need coverage exactly at your stated level. Prefer setting **claim above target** (for example, claim 99%, target 95%) for competitive premiums. +Premiums are **much higher** because you are not offering any headroom — you are not setting **claim above target**. Clients only buy this when they need coverage exactly at your stated level. Prefer setting **claim above target** (for example, claim 99%, target 95%) for competitive premiums. ### You widen confidence (`sla_sigma_x` → 1.0) diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index df1ab3f6..adf465d0 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -5,7 +5,7 @@ Lists a machine for rent. SLA parameters (`--sla_r_target`, `--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). -For SLA listing via REST, see [SLA Offers — API (for automation)](/host/sla-offers#api-for-automation). Volume and duration options below map to REST request fields on `create_asks/`. +For SLA listing via REST, see [SLA Offers — API (for automation)](/host/sla-offers#api-for-automation). Volume and duration options (`-v`, `-z`, `-l`) are available in the CLI today. REST callers should confirm supported `create_asks/` body fields in the [List Machine API reference](/api-reference/machines/list-machine) before sending them — some CLI-only fields may not yet appear in the published OpenAPI schema. ## Usage From f531f1a83ff6e48ce15fc6c3ba73f7aaa7e6955f Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 21:05:19 -0700 Subject: [PATCH 12/45] docs(sla): address doc-review consensus (cycle 10) Add claim headroom guidance, reframe confidence presets, fix search verification jq, and warn against copying backtester p into sla_sigma_x. Co-authored-by: Cursor --- host/hosting-overview.mdx | 2 +- host/sla-offers.mdx | 30 +++++++++++++++++++----------- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index f779ab20..592882c1 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -47,7 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) — same concept as CLI `min_chunk` / `-m` - the offer end date, which determines how long the offer accepts new rental contracts -- **SLA (optional):** Optional uptime guarantee for on-demand rentals — clients pay a small premium; you may owe payouts if uptime misses your published target. You can list without SLA. See [SLA Offers](/host/sla-offers#economics-walkthrough) before enabling. +- **SLA (optional):** Uptime guarantee for on-demand rentals. See [SLA Offers](/host/sla-offers#before-you-enable-sla) to enable and list; read the [economics walkthrough](/host/sla-offers#economics-walkthrough) after you understand target, claim, and confidence. The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index f25fe3a2..e0126134 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -52,6 +52,8 @@ Think of an SLA offer as three linked ideas: 2. **Your reliability claim** — what you believe your machine will actually deliver. 3. **Your confidence** — how sure you are about that claim. Tight confidence means you stand behind a narrow range; wide confidence means a wider defensible range and clients pay a higher premium. +**Claim headroom:** Set **Claim** higher than **Target** unless you intentionally want higher client premiums. Clients pay based on the gap between claim and target; payouts still use **Target**. Example: Target 95%, Claim 99%. + When a client rents an on-demand instance on your SLA-listed offer, Vast measures uptime against your published target and claim percentages: - They pay **compute** (GPU, storage, bandwidth) plus a **small hourly SLA add-on** included in `dph_total`. @@ -82,6 +84,10 @@ When you list or update a machine, set SLA fields via the host console or `PUT / | Reliability claim | `sla_r_claim` | — (backtester sets claim = target) | Your advertised belief about machine uptime. Defaults to the reliability target if omitted. Must be **≥** the target. Same bounds as target (greater than 0, at most 0.9999). | | Confidence spread | `sla_sigma_x` | `p` (different scale — see [backtester](/host/sla-backtester#confidence-values-p)) | How wide your belief is around the claim. Lower = more confident (cheaper for clients). Defaults to `0.5` if omitted. | + +Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x`. They use different scales. Use the preset mapping table below (for example, Normal → `sla_sigma_x=0.5`, which corresponds to backtester `p=0.6667`). + + | Concept | Console | Listing API | Backtester | Client sees | | --- | --- | --- | --- | --- | @@ -111,13 +117,15 @@ Do not assume the dashboard score equals SLA uptime. Before choosing `sla_r_targ **This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** Use the **High / Normal / Wide** presets in the console UI; only set raw `sla_sigma_x` via API after you have saved once in the console. -The **Pricing preset meaning** column below describes what each confidence setting implies for premium sizing — not your uptime target. These presets control pricing spread; the ~83%, ~67%, and ~50% figures describe statistical pricing confidence, not guaranteed uptime: + +Confidence presets control **pricing weight only**, not your uptime obligation. Your obligation is set by **Target**. The statistical weights in the table below (~83% / ~67% / ~50%) describe pricing confidence — do not treat them as uptime targets. + -| Label | Pricing preset meaning | `sla_sigma_x` | Effect on premium | +| Preset | Pricing effect | `sla_sigma_x` | Risk if you miss claim | | --- | --- | --- | --- | -| High | ~83% | `0.2` | Lowest premiums — you are very sure about your claim | -| Normal (default) | ~67% | `0.5` | Balanced default | -| Wide | ~50% | `1.0` | Higher premiums — more uncertainty priced in | +| **High** | Tightest pricing (lowest client premiums) | `0.2` | Highest premium sensitivity | +| **Normal** (default) | Balanced | `0.5` | Moderate | +| **Wide** | Widest pricing band | `1.0` | Lowest premium sensitivity | Higher preset confidence (tighter spread) → lower client premiums, but less room for uptime to slip before payouts. @@ -156,7 +164,7 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove 1. Open your machine on the [Host Machines page](https://cloud.vast.ai/host/machines) → **Set Pricing**. 2. Set base listing fields first (GPU price, offer end date, rental types) if this is a new listing. 3. Expand **SLA**. -4. Set **Reliability target**, **Reliability claim**, and **Confidence** (or a preset). +4. Set **Reliability target**, **Reliability claim**, and **Confidence** (or a preset). Set **Claim** higher than **Target** (for example, 99% claim / 95% target) unless you want higher premiums. 5. Save and confirm the SLA premium preview before listing. 6. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. @@ -345,7 +353,7 @@ When SLA is enabled on an offer, clients see: Verify after listing: ```bash -vastai search offers 'machine_id=12345' --raw | jq '.[0] | {dph_total, price_gpu, expected_reliability, reliability}' +vastai search offers 'machine_id=12345 verified=any' --raw | jq '.offers[0] | {dph_total, expected_reliability, reliability, reliability2}' ``` Premium sizing uses internal SLA math — use the console preview or `dph_total` above, not backtester `total_sla`, when claim exceeds target. @@ -451,13 +459,13 @@ SLA daily settlement (premium kept / payout owed) does not currently emit host w **Linux (GNU date):** ```bash -vastai show earnings --machine_id --start_date $(date -d '7 days ago' +%F) --end_date $(date +%F) +vastai show earnings --machine_id --start_date $(date -u -d '7 days ago' +%F) --end_date $(date -u +%F) ``` **macOS:** ```bash -vastai show earnings --machine_id --start_date $(date -v-7d +%F) --end_date $(date +%F) +vastai show earnings --machine_id --start_date $(date -u -v-7d +%F) --end_date $(date -u +%F) ``` On Windows, use WSL or the API example below. See [`show earnings`](/cli/reference/show-earnings) for all options. @@ -472,7 +480,7 @@ vastai show earnings --machine_id --start_date $(date -u -d 'yesterday' +%F **Linux (GNU date) — seven-day window (do not compare directly to single-day `worst_day_loss`):** ```bash -vastai show earnings --machine_id --start_date $(date -d '7 days ago' +%F) --end_date $(date +%F) --raw \ +vastai show earnings --machine_id --start_date $(date -u -d '7 days ago' +%F) --end_date $(date -u +%F) --raw \ | jq '.per_machine[] | select(.machine_id == or .machine_id == "") | {machine_id, sla_earn}' ``` @@ -502,7 +510,7 @@ This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/ra When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. **Quick rules:** -- **One machine, one UTC day:** use `last_days=1` with `machid` set (or a one-day `start_date`/`end_date` range). There is no per-machine daily SLA series in the API — day-level breakdown for a single machine is easiest in **Host → Billing**. +- **One machine, one UTC day:** use `last_days=1` with `machid` set, or `sday`/`eday` (UTC day indices). The CLI flags `--start_date` and `--end_date` map internally to those fields — they are not separate REST query parameter names on `machine-earnings/`. - **Fleet snapshot:** one request without `machid` returns all machines in `per_machine[]` for the window: ```bash From b73050679834da6da07009532f71b3493e17932c Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 21:09:41 -0700 Subject: [PATCH 13/45] docs(sla): address doc-review consensus (cycle 11) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add console-first onboarding note, Save-vs-LIST update path, fix fleet listing O(n²) pattern, and clarify reboot SLA risk wording. Co-authored-by: Cursor --- host/hosting-overview.mdx | 2 +- host/sla-offers.mdx | 29 ++++++++++++++++++++++++----- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 592882c1..4f16aeb1 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -47,7 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) — same concept as CLI `min_chunk` / `-m` - the offer end date, which determines how long the offer accepts new rental contracts -- **SLA (optional):** Uptime guarantee for on-demand rentals. See [SLA Offers](/host/sla-offers#before-you-enable-sla) to enable and list; read the [economics walkthrough](/host/sla-offers#economics-walkthrough) after you understand target, claim, and confidence. +- **SLA (uptime guarantee):** Optional add-on for on-demand listings. You set three console knobs: **Target** (what clients see), **Claim** (what you expect to deliver), and **Confidence** (how tightly you price around that expectation). Start with [How it works (plain English)](/host/sla-offers#how-it-works-plain-english), then read the [economics walkthrough](/host/sla-offers#economics-walkthrough) before enabling SLA. The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index e0126134..46ec4c1a 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -46,6 +46,16 @@ SLA can be enabled on a first-time listing, but you still need base listing fiel ## How it works (plain English) + +In **Host → Machines → Set Pricing → SLA** you set three knobs only: + +- **Target** — the uptime % clients see in search (your public promise). +- **Claim** — what you expect to deliver (often above Target for pricing headroom). +- **Confidence** — how tightly you price around that expectation (**High / Normal / Wide** — not an uptime %). + +The API field names and backtester aliases below are for automation. Skip them if you use the web console only. + + Think of an SLA offer as three linked ideas: 1. **Reliability target** — the uptime level the listing is priced around (for example, 95% or 99%). @@ -69,7 +79,7 @@ SLA uptime is measured at the **rental contract (instance) level** using platfor - **Instance fails to start** when a client rents → counts against SLA uptime for that contract. - **Machine-level outage** while contracts are active → affects settlement for those contracts. -- **Brief host reboots** during active rentals may count as downtime depending on duration. +- **Brief host reboots** during active rentals may count as downtime if they exceed the platform's measurement window for that UTC day. Vast does not publish a fixed second-level threshold in host docs — treat unplanned reboots as SLA risk. For planned work, use [Scheduled maintenance](#scheduled-maintenance) with at least 24 hours' notice when possible. - **Scheduled maintenance** may receive credit case by case — see [Scheduled maintenance](#scheduled-maintenance). On sliced machines, SLA settles **per rental contract**. If one GPU slice fails but others remain healthy, only contracts on the affected slice are measured for downtime. @@ -115,7 +125,7 @@ Do not assume the dashboard score equals SLA uptime. Before choosing `sla_r_targ ### Confidence presets -**This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** Use the **High / Normal / Wide** presets in the console UI; only set raw `sla_sigma_x` via API after you have saved once in the console. +**This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** Use the **High / Normal / Wide** presets in the console UI. Only set raw `sla_sigma_x` via the API if you need a value outside those presets. Confidence presets control **pricing weight only**, not your uptime obligation. Your obligation is set by **Target**. The statistical weights in the table below (~83% / ~67% / ~50%) describe pricing confidence — do not treat them as uptime targets. @@ -168,6 +178,14 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove 5. Save and confirm the SLA premium preview before listing. 6. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. +#### Updating SLA on an already-listed machine + +If the machine is already **listed** (you previously clicked **LIST** or listed via CLI/REST): + +1. Open **Host → Machines → Set Pricing → SLA**, set Target, Claim, and Confidence, then click **Save**. +2. **Save** applies SLA to the live offer — you do not need to click **LIST** again unless this is a brand-new listing that was never published. +3. Verify in search: `dph_total` includes the SLA add-on and `expected_reliability` matches your Target (see [Search / client-visible fields](#search--client-visible-fields)). + In the web console, **Set Pricing → Save** stores SLA settings; clicking **LIST** publishes the offer to search. `PUT /api/v0/machines/create_asks/` performs both steps in one request — it creates or updates the **live listing** (same as pressing **LIST** or running `vastai list machine`), not a save-only draft. @@ -265,8 +283,9 @@ See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for ```bash export VAST_API_KEY="YOUR_API_KEY" +machines=$(vastai show machines --raw) for id in $(vastai show machines -q); do - body=$(vastai show machines --raw | jq -c --arg id "$id" \ + body=$(echo "$machines" | jq -c --arg id "$id" \ '.machines[] | select((.id|tostring) == $id) | {machine: (.id|tonumber), price_gpu, end_date, min_chunk, sla_r_target: 0.95, sla_r_claim: 0.99, sla_sigma_x: 0.5}') resp=$(curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -H "Authorization: Bearer $VAST_API_KEY" \ @@ -277,7 +296,7 @@ for id in $(vastai show machines -q); do done ``` -Check each response for `success`, `invalid_sla_params`, and `machine_locked` before continuing. Back off on HTTP 429. +Fetch the fleet once before the loop — do not call `show machines --raw` inside the loop. On fleets of 20+ machines, expect several minutes; back off on HTTP 429. **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -434,7 +453,7 @@ Use the [SLA Earnings Backtester](/host/sla-backtester) (API-only; requires a `m - **Listing rejected (`invalid_sla_params`)** — Re-check target, claim, and `sla_sigma_x` against [validation rules](#validation-rules). - **Unexpected payout** — Review uptime; re-run the backtester with a low `reliability` stress value (for example `0.01`). -- **Severe outage** — Disable SLA on new contracts (`sla_r_target=0`); contact [Discord](https://discord.gg/hSuEbSQ4X8) before relisting. +- **Severe outage** — Disable SLA on new contracts: open **Host → Machines** → **Set Pricing → SLA**, set target to `0` (or use API `sla_r_target=0`); contact [Discord](https://discord.gg/hSuEbSQ4X8) before relisting. ## Monitoring SLA after listing From 8678a3946bd33bdfb6feafdbc419d5f0c34c46d6 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 21:13:42 -0700 Subject: [PATCH 14/45] docs(sla): address doc-review consensus (cycle 12) Fix sliced-machine search verification, clarify reliability filter vs expected_reliability, and align machine-scoped sla_earn guidance. Co-authored-by: Cursor --- api-reference/openapi.yaml | 2 +- api-reference/openapi/yaml/show_earnings.yaml | 2 +- host/sla-offers.mdx | 11 +++++++---- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index d2d3d54b..3ae40bde 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -7822,7 +7822,7 @@ paths: description: | Retrieves the earnings history for a specified time range and optionally per machine. - **Fleet scope:** `per_day[]` (including `sla_earn`) is always fleet-wide for the authenticated host, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn` and `summary.total_sla`. + **Fleet scope:** `per_day[]` (including `sla_earn`) is always fleet-wide for the authenticated host, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn`. CLI Usage: `vastai show earnings [options]` security: diff --git a/api-reference/openapi/yaml/show_earnings.yaml b/api-reference/openapi/yaml/show_earnings.yaml index 62580d78..7b47b313 100644 --- a/api-reference/openapi/yaml/show_earnings.yaml +++ b/api-reference/openapi/yaml/show_earnings.yaml @@ -14,7 +14,7 @@ paths: description: | Retrieves the earnings history for a specified time range and optionally per machine. - **Note:** `per_day[]` aggregates SLA earnings across your entire fleet for each UTC day, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn` or `summary.total_sla`. + **Note:** `per_day[]` aggregates SLA earnings across your entire fleet for each UTC day, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn`. CLI Usage: `vastai show earnings [options]` security: diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 46ec4c1a..5e2f1228 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -369,10 +369,13 @@ When SLA is enabled on an offer, clients see: - **`expected_reliability`** — the advertised SLA target (maps to your `sla_r_target`). - **`reliability` / `reliability2`** — historical machine reliability scores, **not** your SLA target. -Verify after listing: +**Filter vs response field:** In search queries, the `reliability` filter uses the machine's historical reliability score — not the SLA target. The published SLA target appears in responses as `expected_reliability`. To select SLA-listed offers programmatically, post-filter on `expected_reliability > 0` (or your minimum target); do not use the `reliability` filter as an SLA selector. + +Verify after listing — filter the offer you care about; sliced machines often return multiple rows (different `num_gpus`, bid vs on-demand): ```bash -vastai search offers 'machine_id=12345 verified=any' --raw | jq '.offers[0] | {dph_total, expected_reliability, reliability, reliability2}' +vastai search offers 'machine_id=12345 verified=any' --raw \ + | jq '[.offers[] | select(.is_bid == false) | {id, num_gpus, dph_total, expected_reliability, reliability}]' ``` Premium sizing uses internal SLA math — use the console preview or `dph_total` above, not backtester `total_sla`, when claim exceeds target. @@ -526,7 +529,7 @@ For API automation only — console users can stop after the Console subsection This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request every two seconds per IP (`threshold=2.0`); back off on HTTP 429. For day-level per-machine reconciliation at scale, prefer console billing reports over high-frequency API polling. -When you pass `machid`, use `per_machine[].sla_earn` and `summary.total_sla` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. +When you pass `machid`, use `per_machine[].sla_earn` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. Do not assume `summary.total_sla` is machine-scoped when `machid` is set — prefer `per_machine[].sla_earn`. **Quick rules:** - **One machine, one UTC day:** use `last_days=1` with `machid` set, or `sday`/`eday` (UTC day indices). The CLI flags `--start_date` and `--end_date` map internally to those fields — they are not separate REST query parameter names on `machine-earnings/`. @@ -555,7 +558,7 @@ Do **not** compare `last_days=7` totals to single-day `worst_day_loss` from the | Field | Good day (meet target) | Bad day (miss target) | | --- | --- | --- | -| `per_machine[].sla_earn` / `summary.total_sla` | Positive (premium kept) | Negative (payout you owe) | +| `per_machine[].sla_earn` | Positive (premium kept) | Negative (payout you owe) | | Fleet `per_day[].sla_earn` | Positive (premium kept) | Negative (payout you owe) | - `{user_id}` — Your account ID (from **Account → Profile** in the console, or `vastai show user`). From 0c88267ecc3dca24766b49271ccecba142efde4b Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 6 Jul 2026 21:42:41 -0700 Subject: [PATCH 15/45] docs(sla): regenerate openapi.yaml from source YAMLs --- api-reference/openapi.yaml | 110 ++++++++++++++++++++----------------- 1 file changed, 60 insertions(+), 50 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 3ae40bde..f0328c46 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4496,20 +4496,14 @@ paths: /api/v0/machines/create_asks: put: summary: list machine - description: 'Creates or updates ask contracts for a machine to list it for - rent on the vast.ai platform. - - Allows setting offer pricing, rental types, end dates, discount rates, - and SLA parameters. - - - SLA request-body fields (sla_r_target, sla_r_claim, sla_sigma_x) are - supported on this REST endpoint. The published CLI and SDK do not yet expose - them — use the host console (Set Pricing → SLA) or REST/curl until CLI/SDK - support ships. - - - CLI Usage (non-SLA fields): `vastai list machine [options]`' + description: "Creates or updates ask contracts for a machine to list it for\ + \ rent on the vast.ai platform.\nAllows setting offer pricing, rental types,\ + \ end dates, discount rates, and SLA parameters.\n\nSLA request-body fields\ + \ (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are supported on this REST\ + \ endpoint. The published CLI and SDK do not yet expose them \u2014 use the\ + \ host console (**Set Pricing \u2192 SLA**) or REST/`curl` until CLI/SDK support\ + \ ships.\n\nCLI Usage (non-SLA fields): `vastai list machine \ + \ [options]`" security: - BearerAuth: [] requestBody: @@ -4561,18 +4555,26 @@ paths: format: float minimum: 0 maximum: 0.9999 - description: "Client reliability coverage target. Values above 0 enable\ - \ SLA on the offer.\nMust be greater than 0 and at most 0.9999\ - \ when enabling SLA; exactly 1.0 is rejected.\nSet to 0 to disable\ - \ SLA. Legacy alias: sla_reliability.\n" + description: 'Client reliability coverage target. Values above 0 + enable SLA on the offer. + + Must be greater than 0 and at most 0.9999 when enabling SLA; exactly + 1.0 is rejected. + + Set to 0 to disable SLA. Legacy alias: sla_reliability. + + ' sla_r_claim: type: number format: float minimum: 0 maximum: 0.9999 - description: "Host reliability claim. Must be greater than 0, at\ - \ most 0.9999, and greater than or equal to sla_r_target.\nDefaults\ - \ to sla_r_target if omitted.\n" + description: 'Host reliability claim. Must be greater than 0, at + most 0.9999, and greater than or equal to sla_r_target. + + Defaults to sla_r_target if omitted. + + ' sla_sigma_x: type: number format: float @@ -4628,7 +4630,8 @@ paths: user_id: 67890 extended: 1 new_contracts: [] - upd_contracts: [1] + upd_contracts: + - 1 '400': description: Bad Request content: @@ -4646,7 +4649,7 @@ paths: type: string example: No such machine(s) for your account '401': - description: Unauthorized — missing permission or invalid API key + description: "Unauthorized \u2014 missing permission or invalid API key" content: application/json: schema: @@ -4661,7 +4664,7 @@ paths: type: string example: Your key lacks the machine_write permission group '403': - description: Forbidden — machine locked + description: "Forbidden \u2014 machine locked" content: application/json: schema: @@ -7819,12 +7822,16 @@ paths: /api/v0/users/{user_id}/machine-earnings: get: summary: show earnings - description: | - Retrieves the earnings history for a specified time range and optionally per machine. + description: 'Retrieves the earnings history for a specified time range and + optionally per machine. + - **Fleet scope:** `per_day[]` (including `sla_earn`) is always fleet-wide for the authenticated host, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn`. + **Note:** `per_day[]` aggregates SLA earnings across your entire fleet for + each UTC day, even when `machid` is set. For machine-scoped SLA totals, use + `per_machine[].sla_earn`. - CLI Usage: `vastai show earnings [options]` + + CLI Usage: `vastai show earnings [options]`' security: - BearerAuth: [] parameters: @@ -7922,7 +7929,8 @@ paths: type: number sla_earn: type: number - description: Net SLA earnings for this machine over the window. + description: Net SLA earnings for this machine over the + window. per_day: type: array items: @@ -7940,7 +7948,9 @@ paths: type: number sla_earn: type: number - description: Net host SLA settlement for the UTC day. Positive when the host keeps premium income; negative when the host pays the client. + description: Net host SLA settlement for the UTC day. Positive + when the host keeps premium income; negative when the + host pays the client. '400': description: Bad Request - Invalid input syntax content: @@ -8800,17 +8810,12 @@ paths: /api/v0/machines: get: summary: show machines - description: 'Fetches data for multiple machines associated with the authenticated - user. - - - The `--raw` CLI output includes listing and SLA fields (`price_gpu`, `end_date`, - `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, etc.) used for read-modify-write - before partial SLA updates. See SLA Offers partial-update workflow in host - documentation. - - - CLI Usage: `vastai show machines [--user_id ]`' + description: "Fetches data for multiple machines associated with the authenticated\ + \ user.\n\nThe `--raw` CLI output includes listing and SLA fields (`price_gpu`,\ + \ `end_date`, `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, etc.) used for\ + \ read-modify-write before partial SLA updates. See [SLA Offers \u2014 Partial\ + \ updates](/host/sla-offers#api-for-automation).\n\nCLI Usage: `vastai show\ + \ machines [--user_id ]`" operationId: getMachines parameters: - name: user_id @@ -8840,22 +8845,27 @@ paths: description: The name of the machine. price_gpu: type: number - description: GPU rental price in $/hour (when present in raw listing output). + description: GPU rental price in $/hour (when present in + raw listing output). end_date: type: number - description: Offer expiration as Unix timestamp (when present in raw listing output). + description: Offer expiration as Unix timestamp (when present + in raw listing output). min_chunk: type: integer description: Minimum GPUs rented together (GPU slicing). sla_r_target: type: number - description: SLA reliability target (0 to disable; greater than 0 and at most 0.9999 when enabled). + description: SLA reliability target (0 to disable; greater + than 0 and at most 0.9999 when enabled). sla_r_claim: type: number - description: SLA reliability claim (must be greater than or equal to target). + description: SLA reliability claim (must be greater than + or equal to target). sla_sigma_x: type: number - description: SLA confidence spread (maps to console High / Normal / Wide presets). + description: SLA confidence spread (maps to console High + / Normal / Wide presets). example: machines: - id: '12345' @@ -9177,16 +9187,16 @@ paths: minimum: 0 exclusiveMinimum: true maximum: 1 - description: Optional flat uptime override (greater than 0 and at most 1) for - all replayed days. Exactly 0 is rejected. + description: Optional flat uptime override (greater than 0 and at most 1) + for all replayed days. Exactly 0 is rejected. - name: beta in: query schema: type: number format: float default: 0.5 - description: Backtest-only timescale weighting. Default 0.5 when omitted. Not - used in live settlement. Contact support before changing. + description: Backtest-only timescale weighting. Default 0.5 when omitted. + Not used in live settlement. Contact support before changing. responses: '200': description: Successful response From 31641e55f974e85fe1cef1c97c9a7b41a6ed0e90 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 13:40:23 -0700 Subject: [PATCH 16/45] docs(sla): align host/client guides to v5 claim model and SLA charge wording Hosts publish claim/confidence only; clients choose target at search. Replace insurance/premium language with SLA charge per HOST-2752 compliance notes. Co-authored-by: Cursor --- api-reference/openapi.yaml | 92 ++--- api-reference/openapi/yaml/list_machine.yaml | 35 +- api-reference/openapi/yaml/show_earnings.yaml | 2 +- api-reference/openapi/yaml/show_machines.yaml | 13 +- api-reference/openapi/yaml/sla_backtest.yaml | 6 +- cli/reference/search-offers.mdx | 6 + docs.json | 1 + .../HOST-2752-SLA-API-Documentation.md | 37 ++ guides/instances/choosing/find-and-rent.mdx | 2 + guides/instances/choosing/sla-coverage.mdx | 189 +++++++++++ host/hosting-overview.mdx | 2 +- host/sla-backtester.mdx | 73 ++-- host/sla-offers.mdx | 317 ++++++++---------- snippets/host/cli/list-machine.mdx | 2 +- snippets/host/sdk/list-machine.mdx | 2 +- 15 files changed, 492 insertions(+), 287 deletions(-) create mode 100644 docs/release-notes/HOST-2752-SLA-API-Documentation.md create mode 100644 guides/instances/choosing/sla-coverage.mdx diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index f0328c46..6fc62732 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4499,11 +4499,13 @@ paths: description: "Creates or updates ask contracts for a machine to list it for\ \ rent on the vast.ai platform.\nAllows setting offer pricing, rental types,\ \ end dates, discount rates, and SLA parameters.\n\nSLA request-body fields\ - \ (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are supported on this REST\ - \ endpoint. The published CLI and SDK do not yet expose them \u2014 use the\ - \ host console (**Set Pricing \u2192 SLA**) or REST/`curl` until CLI/SDK support\ - \ ships.\n\nCLI Usage (non-SLA fields): `vastai list machine \ - \ [options]`" + \ (`sla_r_claim`, `sla_sigma_x`, optional `sla_max_beta`) are supported on\ + \ this REST endpoint. SLA activates when `sla_r_claim > 0`. Host-sent `sla_r_target`\ + \ / legacy `sla_reliability` are ignored \u2014 clients choose coverage at\ + \ search/rent time. The published CLI and SDK do not yet expose SLA fields\ + \ \u2014 use the host console (**Set Pricing \u2192 SLA**) or REST/`curl`\ + \ until CLI/SDK support ships.\n\nCLI Usage (non-SLA fields): `vastai list\ + \ machine [options]`" security: - BearerAuth: [] requestBody: @@ -4550,41 +4552,49 @@ paths: type: number format: float description: Maximum discount rate allowed for prepaid credits - sla_r_target: + sla_r_claim: type: number format: float minimum: 0 maximum: 0.9999 - description: 'Client reliability coverage target. Values above 0 - enable SLA on the offer. + description: 'Host reliability claim. Values above 0 enable SLA + on the offer. Must be greater than 0 and at most 0.9999 when enabling SLA; exactly 1.0 is rejected. - Set to 0 to disable SLA. Legacy alias: sla_reliability. + Set to 0 to disable SLA on new rentals. ' - sla_r_claim: + sla_sigma_x: type: number format: float - minimum: 0 - maximum: 0.9999 - description: 'Host reliability claim. Must be greater than 0, at - most 0.9999, and greater than or equal to sla_r_target. + description: "Host confidence spread \u2014 how wide your belief\ + \ is around the claim.\nMust be greater than 0 and at most 3.0.\ + \ Defaults to 0.5 when enabling SLA.\n" + sla_max_beta: + type: number + format: float + description: 'Optional term capping how path-dependent a client''s + timescale mix can be. - Defaults to sla_r_target if omitted. + Must be in (0, 1) and at least the default beta derived at your + claim. ' - sla_sigma_x: + sla_r_target: type: number format: float - description: "Host confidence spread \u2014 how wide your belief\ - \ is around the claim.\nMust be greater than 0 and at most 3.0.\ - \ Defaults to 0.5.\n" + description: 'Ignored on asks. Client coverage target is supplied + at search/rent time + + (`target_reliability`), not set by the host. + + ' sla_reliability: type: number format: float - description: Legacy alias for sla_r_target. + description: Legacy alias for sla_r_target; ignored on asks. responses: '200': description: Successful response @@ -4624,7 +4634,8 @@ paths: success: true you_sent: machine: 12345 - sla_r_target: 0.95 + sla_r_claim: 0.99 + sla_sigma_x: 0.5 results: - machine_id: 12345 user_id: 67890 @@ -4644,6 +4655,8 @@ paths: enum: - invalid_args - invalid_sla_params + - sla_not_approved + - sla_daemon_outdated example: invalid_sla_params msg: type: string @@ -7949,8 +7962,8 @@ paths: sla_earn: type: number description: Net host SLA settlement for the UTC day. Positive - when the host keeps premium income; negative when the - host pays the client. + when the host keeps the SLA charge; negative when the + host credits the client. '400': description: Bad Request - Invalid input syntax content: @@ -8812,10 +8825,9 @@ paths: summary: show machines description: "Fetches data for multiple machines associated with the authenticated\ \ user.\n\nThe `--raw` CLI output includes listing and SLA fields (`price_gpu`,\ - \ `end_date`, `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, etc.) used for\ - \ read-modify-write before partial SLA updates. See [SLA Offers \u2014 Partial\ - \ updates](/host/sla-offers#api-for-automation).\n\nCLI Usage: `vastai show\ - \ machines [--user_id ]`" + \ `end_date`, `sla_r_claim`, `sla_sigma_x`, etc.) used for read-modify-write\ + \ before partial SLA updates. See [SLA Offers \u2014 Partial updates](/host/sla-offers#api-for-automation).\n\ + \nCLI Usage: `vastai show machines [--user_id ]`" operationId: getMachines parameters: - name: user_id @@ -8854,18 +8866,16 @@ paths: min_chunk: type: integer description: Minimum GPUs rented together (GPU slicing). - sla_r_target: - type: number - description: SLA reliability target (0 to disable; greater - than 0 and at most 0.9999 when enabled). sla_r_claim: type: number - description: SLA reliability claim (must be greater than - or equal to target). + description: Host reliability claim. Values above 0 mean + SLA is enabled on the ask. sla_sigma_x: type: number - description: SLA confidence spread (maps to console High - / Normal / Wide presets). + description: SLA confidence spread around the claim. + sla_max_beta: + type: number + description: Optional cap on client timescale mix (beta). example: machines: - id: '12345' @@ -8873,7 +8883,6 @@ paths: price_gpu: 3.5 end_date: 1735689600 min_chunk: 1 - sla_r_target: 0.95 sla_r_claim: 0.99 sla_sigma_x: 0.5 '401': @@ -9131,7 +9140,7 @@ paths: description: 'Replays a machine''s historical compute earnings and uptime through SLA settlement math - to preview premiums and payouts before listing with SLA. + to preview SLA charges and credits before listing with SLA. Requires `machine_read` permission. See [SLA Earnings Backtester](/host/sla-backtester) @@ -9154,8 +9163,8 @@ paths: minimum: 0 exclusiveMinimum: true maximum: 0.9999 - description: Reliability target to simulate (greater than 0 and at most 0.9999). - Used as both target and claim. Exactly 1.0 is rejected. + description: Reliability level to simulate (greater than 0 and at most 0.9999). + Used as both claim and client target in the simulation. Exactly 1.0 is rejected. - name: p in: query schema: @@ -9195,8 +9204,9 @@ paths: type: number format: float default: 0.5 - description: Backtest-only timescale weighting. Default 0.5 when omitted. - Not used in live settlement. Contact support before changing. + description: "Timescale mix override. For non-admins this is ignored \u2014\ + \ the API derives beta from r (same default a client targeting r would get).\ + \ Admins may override for analysis." responses: '200': description: Successful response diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index 0a10d33d..c23e8eed 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -14,7 +14,7 @@ paths: Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform. Allows setting offer pricing, rental types, end dates, discount rates, and SLA parameters. - SLA request-body fields (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are supported on this REST endpoint. The published CLI and SDK do not yet expose them — use the host console (**Set Pricing → SLA**) or REST/`curl` until CLI/SDK support ships. + SLA request-body fields (`sla_r_claim`, `sla_sigma_x`, optional `sla_max_beta`) are supported on this REST endpoint. SLA activates when `sla_r_claim > 0`. Host-sent `sla_r_target` / legacy `sla_reliability` are ignored — clients choose coverage at search/rent time. The published CLI and SDK do not yet expose SLA fields — use the host console (**Set Pricing → SLA**) or REST/`curl` until CLI/SDK support ships. CLI Usage (non-SLA fields): `vastai list machine [options]` security: @@ -63,33 +63,37 @@ paths: type: number format: float description: Maximum discount rate allowed for prepaid credits - sla_r_target: + sla_r_claim: type: number format: float minimum: 0 maximum: 0.9999 description: | - Client reliability coverage target. Values above 0 enable SLA on the offer. + Host reliability claim. Values above 0 enable SLA on the offer. Must be greater than 0 and at most 0.9999 when enabling SLA; exactly 1.0 is rejected. - Set to 0 to disable SLA. Legacy alias: sla_reliability. - sla_r_claim: + Set to 0 to disable SLA on new rentals. + sla_sigma_x: type: number format: float - minimum: 0 - maximum: 0.9999 description: | - Host reliability claim. Must be greater than 0, at most 0.9999, and greater than or equal to sla_r_target. - Defaults to sla_r_target if omitted. - sla_sigma_x: + Host confidence spread — how wide your belief is around the claim. + Must be greater than 0 and at most 3.0. Defaults to 0.5 when enabling SLA. + sla_max_beta: type: number format: float description: | - Host confidence spread — how wide your belief is around the claim. - Must be greater than 0 and at most 3.0. Defaults to 0.5. + Optional term capping how path-dependent a client's timescale mix can be. + Must be in (0, 1) and at least the default beta derived at your claim. + sla_r_target: + type: number + format: float + description: | + Ignored on asks. Client coverage target is supplied at search/rent time + (`target_reliability`), not set by the host. sla_reliability: type: number format: float - description: Legacy alias for sla_r_target. + description: Legacy alias for sla_r_target; ignored on asks. responses: '200': description: Successful response @@ -129,7 +133,8 @@ paths: success: true you_sent: machine: 12345 - sla_r_target: 0.95 + sla_r_claim: 0.99 + sla_sigma_x: 0.5 results: - machine_id: 12345 user_id: 67890 @@ -148,6 +153,8 @@ paths: enum: - invalid_args - invalid_sla_params + - sla_not_approved + - sla_daemon_outdated example: invalid_sla_params msg: type: string diff --git a/api-reference/openapi/yaml/show_earnings.yaml b/api-reference/openapi/yaml/show_earnings.yaml index 7b47b313..5fe90ee1 100644 --- a/api-reference/openapi/yaml/show_earnings.yaml +++ b/api-reference/openapi/yaml/show_earnings.yaml @@ -132,7 +132,7 @@ paths: type: number sla_earn: type: number - description: Net host SLA settlement for the UTC day. Positive when the host keeps premium income; negative when the host pays the client. + description: Net host SLA settlement for the UTC day. Positive when the host keeps the SLA charge; negative when the host credits the client. '400': description: Bad Request - Invalid input syntax content: diff --git a/api-reference/openapi/yaml/show_machines.yaml b/api-reference/openapi/yaml/show_machines.yaml index 049d370b..761bd7a9 100644 --- a/api-reference/openapi/yaml/show_machines.yaml +++ b/api-reference/openapi/yaml/show_machines.yaml @@ -9,7 +9,7 @@ paths: description: | Fetches data for multiple machines associated with the authenticated user. - The `--raw` CLI output includes listing and SLA fields (`price_gpu`, `end_date`, `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, etc.) used for read-modify-write before partial SLA updates. See [SLA Offers — Partial updates](/host/sla-offers#api-for-automation). + The `--raw` CLI output includes listing and SLA fields (`price_gpu`, `end_date`, `sla_r_claim`, `sla_sigma_x`, etc.) used for read-modify-write before partial SLA updates. See [SLA Offers — Partial updates](/host/sla-offers#api-for-automation). CLI Usage: `vastai show machines [--user_id ]` operationId: getMachines @@ -48,15 +48,15 @@ paths: min_chunk: type: integer description: Minimum GPUs rented together (GPU slicing). - sla_r_target: - type: number - description: SLA reliability target (0 to disable; greater than 0 and at most 0.9999 when enabled). sla_r_claim: type: number - description: SLA reliability claim (must be greater than or equal to target). + description: Host reliability claim. Values above 0 mean SLA is enabled on the ask. sla_sigma_x: type: number - description: SLA confidence spread (maps to console High / Normal / Wide presets). + description: SLA confidence spread around the claim. + sla_max_beta: + type: number + description: Optional cap on client timescale mix (beta). example: machines: - id: "12345" @@ -64,7 +64,6 @@ paths: price_gpu: 3.5 end_date: 1735689600 min_chunk: 1 - sla_r_target: 0.95 sla_r_claim: 0.99 sla_sigma_x: 0.5 '401': diff --git a/api-reference/openapi/yaml/sla_backtest.yaml b/api-reference/openapi/yaml/sla_backtest.yaml index f782b825..eab06390 100644 --- a/api-reference/openapi/yaml/sla_backtest.yaml +++ b/api-reference/openapi/yaml/sla_backtest.yaml @@ -13,7 +13,7 @@ paths: operationId: slaBacktest description: | Replays a machine's historical compute earnings and uptime through SLA settlement math - to preview premiums and payouts before listing with SLA. + to preview SLA charges and credits before listing with SLA. Requires `machine_read` permission. See [SLA Earnings Backtester](/host/sla-backtester) for usage guide. security: @@ -34,7 +34,7 @@ paths: minimum: 0 exclusiveMinimum: true maximum: 0.9999 - description: Reliability target to simulate (greater than 0 and at most 0.9999). Used as both target and claim. Exactly 1.0 is rejected. + description: Reliability level to simulate (greater than 0 and at most 0.9999). Used as both claim and client target in the simulation. Exactly 1.0 is rejected. - name: p in: query schema: @@ -71,7 +71,7 @@ paths: type: number format: float default: 0.5 - description: Backtest-only timescale weighting. Default 0.5 when omitted. Not used in live settlement. Contact support before changing. + description: Timescale mix override. For non-admins this is ignored — the API derives beta from r (same default a client targeting r would get). Admins may override for analysis. responses: '200': description: Successful response diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 598ea681..4d24bacd 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -81,6 +81,9 @@ bool = True | False # reliable single RTX 3090, no conflicts with stopped instances vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False' +# SLA offers: host claim ≥ 99%, your coverage target 95% (see SLA Coverage) +vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --order dph_total + # datacenter GPUs with minimum compute capability and TFLOPs vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True' @@ -145,6 +148,9 @@ vastai search offers 'cpu_arch=arm64' | `pci_gen` | float | PCIE generation | | `pcie_bw` | float | PCIE bandwidth (CPU to GPU) | | `reliability` | float | machine reliability score (see FAQ for explanation) | +| `expected_reliability` | float | host SLA claim (`sla_r_claim`); `0` when SLA is off | +| `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | +| `target_reliability` | float | your desired SLA coverage level; drives SLA charge in `dph_total` | | `rentable` | bool | is the instance currently rentable | | `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances | | `storage_cost` | float | storage cost in $/GB/month | diff --git a/docs.json b/docs.json index 038a1157..62713899 100644 --- a/docs.json +++ b/docs.json @@ -42,6 +42,7 @@ "pages": [ "guides/instances/choosing/overview", "guides/instances/choosing/find-and-rent", + "guides/instances/choosing/sla-coverage", "guides/instances/choosing/instance-types", "guides/instances/choosing/templates", "guides/instances/choosing/reserved-instances" diff --git a/docs/release-notes/HOST-2752-SLA-API-Documentation.md b/docs/release-notes/HOST-2752-SLA-API-Documentation.md new file mode 100644 index 00000000..23ef8f96 --- /dev/null +++ b/docs/release-notes/HOST-2752-SLA-API-Documentation.md @@ -0,0 +1,37 @@ +# HOST-2752: Host & client SLA documentation + +**Branch:** `HOST-2752-SLA-API-Documentation` +**Base:** `origin/main` +**Scope:** User-facing SLA docs aligned to v5 ask/search model and compliance wording. + +## Summary + +Documents SLA for hosts and clients under the current design: hosts publish a **claim** and **confidence** (`sla_r_claim`, `sla_sigma_x`); clients choose **target** at search/rent (`target_reliability`). User-facing copy uses **SLA charge** (not premium) and avoids insurance/betting language. + +## Details + +### Guides + +| Page | Path | Audience | +| --- | --- | --- | +| SLA Offers | `/host/sla-offers` | Hosts — claim/confidence listing, economics, monitoring | +| SLA Earnings Backtester | `/host/sla-backtester` | Hosts — historical replay (`r` = claim=target in sim) | +| SLA Coverage | `/guides/instances/choosing/sla-coverage` | Clients — search filters, charges, credits | + +### Model corrections vs earlier drafts + +- `sla_r_target` is **not** host-settable on asks (ignored if sent). +- SLA activates on `sla_r_claim > 0`; disable with `sla_r_claim = 0`. +- Optional `sla_max_beta` documented for advanced hosts. +- Backtester `beta` is derived from `r` for non-admins. +- Billing note: intended compute billed; compensation via settlement credits. + +### OpenAPI / nav + +- `list_machine.yaml`, `show_machines.yaml`, `sla_backtest.yaml`, `show_earnings.yaml` updated; `openapi.yaml` regenerated. +- `docs.json` adds client SLA Coverage under Find & rent. +- Search CLI docs list `has_sla`, `expected_reliability`, `target_reliability`. + +## Compliance wording + +Forbidden in user docs: insurance, premium (prefer **SLA charge**), betting, gambling, bet. API field names such as `slaPremiumPerHour` are documented as the SLA charge rate without using “premium” as prose. diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index 6db382bb..af0b89be 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -80,6 +80,8 @@ Click on the "Change Template" button to bring up the template config menu that ![Edit](https://vast.ai/uploads/Search/Edit.png) +Some offers include an optional **SLA** reliability guarantee. To filter and compare SLA-backed rentals, see [SLA Coverage](/guides/instances/choosing/sla-coverage). + ## Common Questions ### I can't search for instances. I am getting the error "Error: invalid\_request 0 is not a valid search op" diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx new file mode 100644 index 00000000..886c5f1b --- /dev/null +++ b/guides/instances/choosing/sla-coverage.mdx @@ -0,0 +1,189 @@ +--- +title: "SLA Coverage" +description: "Rent GPU instances with reliability guarantees. Learn how SLA charges, credits, and search filters work." +"canonical": "/guides/instances/choosing/sla-coverage" +--- + +Some Vast.ai offers include a **Service Level Agreement (SLA)** — a reliability guarantee bundled with your on-demand rental. You choose a reliability **target** when you search, pay a small hourly **SLA charge** on top of compute, and if measured reliability falls short of that target, you receive settlement credits. + +This page explains SLA from the renter side: how to find SLA offers, how pricing works, and when you get credited. + + +You do not post escrow or collateral for SLA. You pay the SLA charge while the instance runs. Settlement happens automatically on a daily cadence. + + +## What SLA protects + +SLA is a **contractual, per-rental** reliability guarantee with automatic daily settlement. It is **not** the same as [verification](/host/understanding-verification) or the **reliability score** shown on offer cards — those are platform trust signals. + +For SLA-covered on-demand contracts: + +- Compute is billed for the **intended** rental day (offline time is tracked as an outage in reliability measurements). +- **Settlement credits** compensate you when measured reliability falls short of your chosen target. +- On strong-reliability days, you simply pay the SLA charge with no credit. + +SLA is most useful for **long-running production workloads** where unexpected downtime has a real cost beyond the hourly rate. + +## How pricing works + +Total hourly cost with SLA: + +``` +total ≈ GPU + storage + bandwidth + SLA charge +``` + +The SLA charge depends on: + +| Factor | Where it comes from | Effect | +| --- | --- | --- | +| Your reliability target | Your search filter (`target_reliability`) | Higher target → higher SLA charge | +| Host reliability claim | `expected_reliability` on the offer | Higher claim → lower SLA charge (at a given target) | +| Host confidence | Derived from `sla_sigma_x` on the offer | Tighter confidence → lower SLA charge | + +**Rule of thumb:** pick a target **at or below** the host's claim for the best value. If you ask for 99% coverage on a host who only claims 95%, the SLA charge is much higher than asking for 95% on a host who claims 99%. + +### Example: H100 at $3.50/hr GPU + +Searching with **target reliability 95%** on an offer where the host **claims 99%** with normal confidence: + +| Cost component | Approx. rate | +| --- | --- | +| GPU compute | $3.50/hr | +| SLA charge | ~$0.008/hr | +| **Total** | ~$3.51/hr | + +The SLA charge is a small fraction of compute when the host's claim comfortably exceeds your target. + +## Finding SLA offers + +### Search filters + +Use these filters in [Search](https://cloud.vast.ai/create/) or the [search offers API](/api-reference/search/search-offers): + +| Filter | Meaning | Example | +| --- | --- | --- | +| `target_reliability` | Your desired reliability level. Also drives SLA charge calculation and ranking. | `target_reliability=0.95` | +| `has_sla` | Restrict to offers with (or without) SLA enabled. | `has_sla=true` | +| `expected_reliability` | Filter by the host's advertised claim. | `expected_reliability>=0.99` | + +**CLI examples:** + +```bash +# SLA offers where the host claims at least 99% reliability +vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' + +# Compare total cost including SLA charge +vastai search offers 'has_sla=true target_reliability=0.95 num_gpus=1' --order dph_total +``` + +When you set `target_reliability`, search results include: + +| Response field | Meaning | +| --- | --- | +| `search.slaPremiumPerHour` | SLA charge for this offer at your target (API field name; this is the SLA charge rate) | +| `dph_total` | Total hourly cost **including** the SLA charge | +| `expected_reliability` | Host's reliability claim | + +Hover the price breakdown on an offer card to see GPU, storage, bandwidth, and the SLA charge separately. + + +When you search with an SLA target, **reserved-instance discounts are not applied** to the displayed total. SLA charges are never discounted. + + +### Comparing offers + +Two offers at the same GPU price can have very different SLA costs: + +| Offer | GPU/hr | Host claim | Your target | SLA charge/hr | +| --- | --- | --- | --- | --- | +| A | $3.50 | 99% | 95% | ~$0.008 | +| B | $3.50 | 95% | 95% | much higher | + +Offer A is dramatically cheaper on SLA because the host claims more headroom above your target. Always compare **`dph_total`**, not just GPU price, when SLA matters. + +Search ranking also accounts for SLA cost — offers with expensive coverage at your target rank lower per dollar of performance. + +## What happens after you rent + +When you rent an SLA-backed offer: + +1. **Contract terms lock in** — your reliability target, the host's claim, and confidence spread are fixed for that rental. +2. **Daily billing** — you pay compute plus the SLA charge each day. +3. **Daily settlement** — Vast measures reliability across multiple timescales and calculates any SLA credit. +4. **Credits appear in billing** — positive credits improve your balance; strong days mean you paid the SLA charge with no credit. + +### How reliability is measured + +Each day, the platform tracks how long your instance was online. Settlement considers **multiple time windows** — from short intervals out to long contract-scale windows — so: + +- A single bad hour hurts, but does not always trigger the maximum credit. +- A pattern of unreliable uptime produces larger credits over time. +- One strong day after a weak week does not instantly reset everything. + +Scheduled maintenance with adequate notice may be credited toward reliability. Unplanned outages count fully. + +### Credit scenarios (simplified) + +Using the H100 example ($84/day compute, ~$0.20/day SLA charge, target 95%, host claim 99%): + +| Day's measured reliability (simplified) | What you pay | What you receive | Your net vs no-SLA baseline | +| --- | --- | --- | --- | +| Excellent (~100%) | $84 compute + $0.20 SLA charge | — | −$0.20 | +| Good (~99%) | $84 + $0.20 | Small credit | Roughly −$0.17 | +| At target (~95%) | $84 + $0.20 | ~$42 credit | ~+$42 | +| Severe outage (~90% or less) | $84 + $0.20 | ~$84 credit | ~+$84 | + + +Production settlement uses the multi-window reliability blend described above, not a single raw daily percentage. Treat these rows as directional, not exact invoice amounts. + + +### Settlement timing + +- Settlement runs **once per day** for the previous billing day. +- Credits accumulate on your instance charges and transfer to your account balance. +- When your contract ends, any remaining unsettled days are resolved at close. + +## Viewing SLA on active instances + +On the [Instances](https://cloud.vast.ai/instances/) page, price details for SLA rentals include the SLA charge rate alongside GPU and storage costs. + +The [show instances API](/api-reference/instances/show-instances) exposes SLA fields on each contract: + +| Field | Meaning | +| --- | --- | +| `target_reliability` | Your coverage target | +| `sla_r_claim` | Host's claim | +| `sla_sigma_x` | Host's confidence spread | +| `search.slaPremiumPerHour` | Current SLA charge rate (API field name) | + +Filter active instances with `has_sla=true` in the query. + +## When SLA is not available + +- **Prepaid / reserved-only flows** may reject SLA parameters. Use on-demand rentals for SLA coverage. +- Offers without SLA (`expected_reliability = 0` / `has_sla=false`) are excluded when you filter with `has_sla=true` or set a positive `target_reliability`. +- If SLA parameters on an offer are invalid for your target, search may flag an SLA pricing error instead of showing a charge. + +## FAQ + +### Do I need SLA for every rental? + +No. For short experiments or fault-tolerant batch jobs, standard on-demand rentals without SLA may be enough. SLA is for workloads where reliability has a real dollar cost. + +### Can I change my reliability target mid-rental? + +No. The target is fixed when the contract is created. End the instance and rent again with a different search filter if you need a different level. + +### Does SLA replace verification? + +No. Verification is a platform quality signal. SLA is a financial guarantee on a specific contract. A verified machine can still have SLA; an unverified machine may also offer SLA. + +### Where do I see historical SLA credits? + +Check your billing history and instance charges. SLA line items appear alongside compute charges for each settled day. + +## Related documentation + +- [SLA Offers (hosts)](/host/sla-offers) — how hosts configure and price SLA listings +- [Finding & Renting Instances](/guides/instances/choosing/find-and-rent) — search basics and offer cards +- [Instance Pricing](/guides/instances/pricing) — on-demand, interruptible, and reserved pricing diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 4f16aeb1..5457b68e 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -47,7 +47,7 @@ The main offer parameters include: - the min bid price for [interruptible](/guides/instances/rental-types) instances - the min_gpu param controlling 'slicing' (explained below) — same concept as CLI `min_chunk` / `-m` - the offer end date, which determines how long the offer accepts new rental contracts -- **SLA (uptime guarantee):** Optional add-on for on-demand listings. You set three console knobs: **Target** (what clients see), **Claim** (what you expect to deliver), and **Confidence** (how tightly you price around that expectation). Start with [How it works (plain English)](/host/sla-offers#how-it-works-plain-english), then read the [economics walkthrough](/host/sla-offers#economics-walkthrough) before enabling SLA. +- **SLA (uptime guarantee):** Optional add-on for on-demand listings. You set a **Claim** (reliability you believe you can deliver) and **Confidence** (how tightly SLA charges are priced around that claim). Clients choose their own reliability **target** at search/rent time. Start with [How it works (plain English)](/host/sla-offers#how-it-works-plain-english), then read the [economics walkthrough](/host/sla-offers#economics-walkthrough) before enabling SLA. Renters: see [SLA Coverage](/guides/instances/choosing/sla-coverage). The offer accepts new rentals until the offer end date. When a client rents an instance on your machine, a rental contract is created from your offer. If your machine has multiple GPUs and you've set min_gpu to allow slicing, multiple clients can rent from the same offer, each creating their own independent rental contract. diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 84df6947..6bac61be 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -1,16 +1,16 @@ --- title: "SLA Earnings Backtester" -description: "Replay your machine's historical earnings through SLA math to preview premiums and payouts before listing." +description: "Replay your machine's historical earnings through SLA math to preview SLA charges and credits before listing." "canonical": "/host/sla-backtester" --- -The **SLA (Service Level Agreement) earnings backtester** lets you answer a practical question before you list: *if I had offered SLA at reliability target **`r`** and confidence level **`p`**, how would that have affected my earnings on this machine over the last few months?* +The **SLA (Service Level Agreement) earnings backtester** lets you answer a practical question before you list: *if clients had rented with reliability target **`r`** and I offered SLA at confidence **`p`**, how would that have affected my earnings on this machine over the last few months?* -**Console hosts:** use **Set Pricing → SLA** in the web console to preview premiums — you do not need this API. +**Console hosts:** use **Set Pricing → SLA** in the web console to preview SLA charges — you do not need this API. -**API hosts:** this endpoint replays historical earnings through SLA math to estimate premiums and worst-day payout risk before listing. (**`r`** = reliability target; **`p`** = host confidence — both defined in [Query parameters](#query-parameters) below.) +**API hosts:** this endpoint replays historical earnings through SLA math to estimate SLA charges and worst-day credit risk before listing. (**`r`** = reliability level used as both claim and target in the simulation; **`p`** = host confidence — both defined in [Query parameters](#query-parameters) below.) -It replays your machine's **real historical compute earnings and uptime** through the same SLA settlement math used in production, then compares the simulated result to what you actually earned from SLA (if anything). +It replays your machine's **real historical compute earnings and reliability** through the same SLA settlement math used in production, then compares the simulated result to what you actually earned from SLA (if anything). See [Choose your path](#choose-your-path) below. @@ -34,8 +34,8 @@ If `has_data` is `false`, widen the date range or pick a machine with more renta Use the backtester to: -- Pick a reliability target and confidence before you enable SLA on a listing -- Compare how premium and worst-case payout change across targets +- Pick a reliability claim and confidence before you enable SLA on a listing +- Compare how SLA charge and worst-case credit change across targets - Stress-test a lower reliability assumption before you commit - Compare to history — each day includes `historical_sla`, your machine's realized SLA earnings on that day (zero if you were not offering SLA) @@ -43,21 +43,21 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). ## How it works -1. You choose a machine, date range, reliability target (`r`), and confidence (`p`). +1. You choose a machine, date range, reliability level (`r`), and confidence (`p`). 2. The API loads per-day earnings from your machine's rental history. 3. For each active day, it computes GPU, storage, and bandwidth earnings plus simulated SLA host earnings. 4. It returns a day-by-day breakdown and summary totals. -**Simulated vs listing parameters.** In the backtester, reliability target and claim are both set to **`r`** — the backtester cannot set `sla_r_claim` above `sla_r_target`. Claim-headroom simulation is console-only today. When you actually list a machine, you can set **`sla_r_claim` above `sla_r_target`** for lower client premiums. Workflow: backtest `worst_day_loss` at your target, then verify visible premiums in **Set Pricing → SLA** (or `dph_total` in search) before listing with claim above target. +**Simulated vs listing parameters.** In the backtester, reliability **claim and client target are both set to `r`**. That is a conservative what-if: it pretends every client targeted your claim. When you list, you set only **`sla_r_claim`** (and `sla_sigma_x`); clients choose their own `target_reliability` at search/rent time. Workflow: backtest `worst_day_loss` at a candidate claim level, then verify visible SLA charges in **Set Pricing → SLA** (or `dph_total` in search at realistic client targets) before listing. -**Active vs idle days.** **Idle days** are days with no rental earnings on the machine (no active compute rental). These days typically produce no SLA premium or payout in the simulation. Days with no rental activity appear in the results as zero-filled rows but do not count toward `covered_days`. Only days with actual earnings are replayed through SLA math. +**Active vs idle days.** **Idle days** are days with no rental earnings on the machine (no active compute rental). These days typically produce no SLA charge or credit in the simulation. Days with no rental activity appear in the results as zero-filled rows but do not count toward `covered_days`. Only days with actual earnings are replayed through SLA math. **Simulation vs live listing** -- The backtester sets claim equal to target and may show higher premiums than live listing or the console preview. -- For client-visible pricing (`dph_total`), use **Set Pricing → SLA** in the console. +- The backtester sets claim equal to target and may show higher SLA charges than live listing when clients choose targets below your claim. +- For client-visible pricing (`dph_total`), use **Set Pricing → SLA** in the console or search with a realistic `target_reliability`. - For tail risk, trust `worst_day_loss`, not headline `total_sla`. -- The backtester defaults `beta` to `0.5` when omitted. Live SLA settlement does **not** use this default — weighting is fixed when you list. Treat `total_sla` as a tail-risk estimate, not an exact live preview. +- Timescale mix (`β`) is derived from `r` for non-admin callers (same default a client targeting `r` would get). Admin overrides of `beta` are ignored for non-admins. ## Before you start @@ -81,21 +81,17 @@ GET /api/v0/host/sla_backtest/ Requires Bearer authentication. This endpoint is rate-limited like other host API endpoints — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors) for retry guidance. - -Find your API key under **Account → API Keys** (requires [`machine_read`](/api-reference/permissions) permission). See [Create API Key](/api-reference/accounts/create-api-key) if you need a new key. Your machine ID appears on the [Host Machines page](https://cloud.vast.ai/host/machines) or via [`vastai show machines`](/host/cli/show-machines). - - ### Query parameters | Parameter | Required | Description | | --- | --- | --- | | `machine_id` | Yes | ID of your machine | -| `r` | Yes | Reliability target to simulate (greater than 0 and at most **0.9999**). Used as both target and claim. Example: `0.95` = 95%. Exactly `1.0` is rejected. | +| `r` | Yes | Reliability level to simulate (greater than 0 and at most **0.9999**). Used as **both claim and client target** in the simulation. Example: `0.95` = 95%. Exactly `1.0` is rejected. | | `p` | No | Host confidence (greater than 0 and **less than 1** — not equal to 1). Maps to the same spread used when listing with `sla_sigma_x` — see [Confidence values](#confidence-values-p) below. Default: `0.6667` (normal confidence, ≈ 67%). | | `start_date` | No | Range start as Unix epoch seconds. Default: 90 days before `end_date`. | | `end_date` | No | Range end as Unix epoch seconds. Default: now. | | `reliability` | No | Optional flat uptime override (greater than 0 and at most 1). Ignores historical uptime — useful for what-if analysis. Use `0.01` to approximate near-total downtime; `0` is rejected with `400 bad_request`. | -| `beta` | No | Backtest-only timescale weighting. Default `0.5` when omitted. **Not used in live settlement.** Contact support before changing. | +| `beta` | No | Timescale mix override. For non-admins this is **ignored** — the API derives β from `r` (same default a client targeting `r` would get). Admins may override for analysis. | ### Limits @@ -133,7 +129,7 @@ Compare two confidence levels on the same history: curl -s -H "Authorization: Bearer YOUR_API_KEY" \ "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.6667" -# High confidence (~83%) — tighter spread, lower simulated premiums +# High confidence (~83%) — tighter spread, lower simulated SLA charges curl -s -H "Authorization: Bearer YOUR_API_KEY" \ "https://console.vast.ai/api/v0/host/sla_backtest/?machine_id=12345&r=0.99&p=0.83" ``` @@ -210,7 +206,7 @@ A successful response looks like this (fields abbreviated): | --- | --- | | `gpu`, `storage`, `bandwidth` | That day's compute earnings breakdown ($) | | `uptime` | Uptime fraction for the day (0–1), or your flat override if set | -| `sla` | **Simulated SLA host earnings** for the day. Positive = you keep premium; negative = you pay the client | +| `sla` | **Simulated SLA host earnings** for the day. Positive = you keep the SLA charge; negative = you credit the client | | `historical_sla` | What you **actually** earned from SLA that day (signed). Zero if you were not offering SLA | Review `sla` day by day in `daily_results` to see which days would have helped or hurt under the chosen parameters. Compare against `historical_sla` to see how simulated economics differ from reality. @@ -223,46 +219,46 @@ Review `sla` day by day in `daily_results` to see which days would have helped o | `total_sla` | Net simulated SLA earnings. Positive = SLA would have added income overall | | `total_earnings` | Compute + simulated SLA | | `total_historical_sla` | Sum of realized historical SLA in the range | -| `worst_day_loss` | Largest single-day client payout (your worst simulated loss). Always a non-negative dollar amount — unlike signed `sla` / `sla_earn` fields | +| `worst_day_loss` | Largest single-day client credit (your worst simulated loss). Always a non-negative dollar amount — unlike signed `sla` / `sla_earn` fields | | `reserve` | Reserved for future use — ignore in production decisions today. | ## Interpreting results ### Mostly positive `sla` values -Your historical uptime was strong relative to the target. SLA would likely have been a net positive — small premiums on good days, few days with payouts. +Your historical reliability was strong relative to the simulated target. SLA would likely have been a net positive — small SLA charges on strong days, few days with credits. ### Negative `sla` on specific days -Those days had uptime below your chosen target. The magnitude shows how much you would have paid out. If you see clusters of negative days, consider a lower target, wider confidence, or fixing reliability before listing SLA. +Those days had reliability below the simulated target. The magnitude shows how much you would have credited. If you see clusters of negative days, consider a lower claim, wider confidence, or fixing reliability before listing SLA. ### `total_sla` near zero -Break-even territory — premiums and payouts roughly balance. Typical when your actual uptime matches your stated target. +Break-even territory — SLA charges and credits roughly balance. Typical when your actual reliability matches the simulated target. ### `total_sla` strongly negative -Under the simulated parameters, SLA would have cost you money over this window. Either improve uptime, lower the target, or widen confidence before listing. +Under the simulated parameters, SLA would have cost you money over this window. Either improve reliability, lower the claim, or widen confidence before listing. ### Using `reliability` override -Setting `reliability=0.90` while keeping `r=0.99` answers: *if every active day had 90% uptime, how bad would SLA payouts get?* Use this to understand worst-case payout exposure before committing to a high target. +Setting `reliability=0.90` while keeping `r=0.99` answers: *if every active day had 90% uptime, how bad would SLA credits get?* Use this to understand worst-case credit exposure before committing to a high claim. ## Confidence values (`p`) -**`p` and `sla_sigma_x` use different scales** — do not copy numeric values between them. For example, `p=0.5` (Wide confidence) maps to `sla_sigma_x ≈ 1.0`, not `0.5`. Use the table below to translate between the two. +**`p` and `sla_sigma_x` use different scales** — do not copy numeric values between them. For example, `p=0.5` (wide confidence) maps to `sla_sigma_x ≈ 1.0`, not `0.5`. Use the table below to translate between the two. -The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. The mappings below match the presets used when listing: +The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. The mappings below match common listing values: | Confidence `p` | Approx. label | Listing equivalent | | --- | --- | --- | -| `0.83` | High | `sla_sigma_x ≈ 0.2` | +| `0.83` | Tight | `sla_sigma_x ≈ 0.2` | | `0.6667` | Normal (default) | `sla_sigma_x ≈ 0.5` | | `0.50` | Wide | `sla_sigma_x ≈ 1.0` | -Higher confidence (higher `p`) → tighter spread → lower premiums for clients, but less room for uptime to slip before payouts. +Higher confidence (higher `p`) → tighter spread → lower SLA charges for clients at a given target, but less room for reliability to slip before credits grow. ## Error responses @@ -278,14 +274,14 @@ For missing or invalid API keys and permission denials (`machine_read`), see [Au ## Recommended workflow 1. **Run a baseline backtest** on a machine with at least a few weeks of rental history: - - Check your machine's uptime history on the [Host Machines page](https://cloud.vast.ai/host/machines), then use the console SLA preview or backtester — do not rely on the dashboard reliability score alone (see [Machine reliability score vs SLA uptime](/host/sla-offers#machine-reliability-score-vs-sla-uptime)). - - Choose a target at or slightly below your current reliability for your first backtest. + - Check your machine's uptime history on the [Host Machines page](https://cloud.vast.ai/host/machines), then use the console SLA preview or backtester — do not rely on the dashboard reliability score alone (see [Machine reliability score vs SLA reliability](/host/sla-offers#machine-reliability-score-vs-sla-reliability)). + - Choose an `r` at or slightly below the claim you plan to publish. - Use normal confidence (`p=0.6667`). - If `has_data` is `false`, widen the date range or wait for more rental history. -2. **Check `worst_day_loss`** — can you absorb that payout from a bad day? -3. **Try a higher target** (for example `r=0.99`) and see how `total_sla` changes. -4. **Run a stress test** with `reliability=0.90` at your intended target. -5. **List with headroom** — set `sla_r_claim` above `sla_r_target` on the actual offer for better client pricing than the backtester shows (the backtester uses target = claim; see [SLA Offers](/host/sla-offers)). +2. **Check `worst_day_loss`** — can you absorb that credit from a bad day? +3. **Try a higher `r`** (for example `0.99`) and see how `total_sla` changes. +4. **Run a stress test** with `reliability=0.90` at your intended claim. +5. **List with `sla_r_claim`** — set claim (and `sla_sigma_x`) on the offer; clients choose their own targets in search (see [SLA Offers](/host/sla-offers)). ## Fleet workflow @@ -315,7 +311,7 @@ done Expect roughly two seconds per machine minimum (`sleep 2` plus request time). For 50 machines, budget at least a few minutes. Run off-peak before a fleet SLA rollout. On `429`, back off per [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Parallel requests are not recommended unless you implement backoff. 3. Compare `worst_day_loss` and `total_sla` across machines. -4. Apply `sla_r_claim` headroom when listing via the API (see [SLA Offers](/host/sla-offers#api-for-automation)). +4. Apply `sla_r_claim` / `sla_sigma_x` when listing via the API (see [SLA Offers](/host/sla-offers#api-for-automation)). ## When stuck @@ -327,4 +323,5 @@ Expect roughly two seconds per machine minimum (`sleep 2` plus request time). Fo - [SLA Backtest API](/api-reference/host/sla-backtest) — formal API reference for this endpoint - [SLA Offers](/host/sla-offers) — listing parameters, economics, and risk scenarios +- [SLA Coverage (clients)](/guides/instances/choosing/sla-coverage) — how renters choose targets and read `dph_total` - [API permissions](/api-reference/permissions) — `machine_read` scope required diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 5e2f1228..eb18540a 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -1,23 +1,19 @@ --- title: "SLA Offers" -description: "Offer reliability guarantees on your machines, set SLA parameters, and understand how premiums and payouts work." +description: "Offer reliability guarantees on your machines, set claim and confidence, and understand how SLA charges and payouts work." "canonical": "/host/sla-offers" --- -Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is reliability insurance: the client pays a small hourly SLA add-on included in **`dph_total`** (dollars per hour total in search — base compute plus SLA premium), and if uptime falls short of the agreed target, the client receives a payout from your earnings. +Vast.ai lets hosts attach a **Service Level Agreement (SLA)** to a machine listing. An SLA is a reliability guarantee: clients who choose coverage pay a small hourly **SLA charge** included in **`dph_total`** (dollars per hour total in search — base compute plus SLA charge), and if measured reliability falls short of their chosen target, they receive a settlement credit funded from your earnings. -This page explains how SLA offers work from the host side — what you are promising, how pricing is calculated, and what happens when uptime is good or bad. +This page explains how SLA offers work from the host side — what you set, how clients choose coverage, and what happens when uptime is good or bad. -SLA settlement is **lopsided by design**: when uptime is good, you keep the premium, but when uptime is bad, client payouts can exceed the premium you collected that day. Premiums and payouts are settled daily based on measured uptime. You can optionally preview SLA economics before listing — use the [SLA backtester](/host/sla-backtester) (API, requires rental history) or the web console SLA preview (**Set Pricing → SLA**). The console preview works on first-time listings. +SLA settlement is **asymmetric by design**: when reliability is strong relative to the client's target, you keep the SLA charge; when it falls short, client credits can exceed the charge you collected that day. Charges and credits settle on a daily cadence. Preview economics with the [SLA backtester](/host/sla-backtester) (API, requires rental history) or the web console SLA preview (**Set Pricing → SLA**). -**Clients:** see [What your clients see](#what-your-clients-see) below for how SLA appears in search and billing. - - - -Clients pay a small hourly SLA add-on included in `dph_total` (for example, ~$0.008/hr on top of the base GPU rate). On SLA-listed on-demand offers, coverage is included automatically when the client rents — no separate host-side toggle at rent time. The published **target %** appears in search and the rent flow alongside `dph_total`. Premiums and payouts settle once per UTC calendar day; credits typically post to **Billing** within a few hours after UTC midnight (exact timing can vary). If uptime falls below the promised target, credits are applied automatically. SLA applies to on-demand rentals only — not [interruptible](/guides/instances/rental-types) instances. +**Clients:** see [SLA Coverage](/guides/instances/choosing/sla-coverage) for how SLA appears in search and billing. ## Choose your path @@ -27,7 +23,7 @@ Clients pay a small hourly SLA add-on included in `dph_total` (for example, ~$0. | Preview economics and enable SLA in the console | [How it works](#how-it-works-plain-english) → [Listing an SLA offer](#listing-an-sla-offer) | | Enable or update SLA via API | [Before you enable SLA](#before-you-enable-sla) → [API (for automation)](#api-for-automation) | | I list with CLI only (no SLA flags yet) | **Set Pricing → SLA** + **LIST** in the console, or REST `PUT /api/v0/machines/create_asks/` — SLA flags are **not** in `vastai list machine` yet | -| Monitor payouts after listing | [Monitoring SLA after listing](#monitoring-sla-after-listing) | +| Monitor settlement after listing | [Monitoring SLA after listing](#monitoring-sla-after-listing) | ## Before you enable SLA @@ -35,137 +31,128 @@ Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machin Before enabling SLA, finish normal listing setup: test your machine, set GPU price and offer end date, choose on-demand vs interruptible, and understand [Testing your own machine](/host/hosting-overview#testing-your-own-machine) and offer terms in [Hosting overview](/host/hosting-overview). -SLA can be enabled on a first-time listing, but you still need base listing fields (GPU price, offer end date, etc.). See [Listing an SLA offer](#listing-an-sla-offer) and [Offer End Date](/host/hosting-overview#offer-end-date). +SLA listing may require host approval and a sufficiently recent daemon. If listing fails with `sla_not_approved` or `sla_daemon_outdated`, contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or update the daemon from the host setup page. **Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. Interruptible instances on an SLA-enabled machine are not SLA-covered; on-demand contracts on the same machine are. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. - Optional: run the [backtester](/host/sla-backtester) after you have weeks of history; otherwise use the web console SLA preview and the economics walkthrough on this page. -- **New or low-history machines:** If the backtester returns `has_data: false`, rely on the web console SLA preview and the economics walkthrough below. Wait for rental history before trusting `worst_day_loss`. Consider wider confidence or lower targets until you have a few weeks of data. +- **New or low-history machines:** If the backtester returns `has_data: false`, rely on the web console SLA preview. Wait for rental history before trusting `worst_day_loss`. Consider wider confidence or a more conservative claim until you have a few weeks of data. ## How it works (plain English) -In **Host → Machines → Set Pricing → SLA** you set three knobs only: +In **Host → Machines → Set Pricing → SLA** you set host knobs only: -- **Target** — the uptime % clients see in search (your public promise). -- **Claim** — what you expect to deliver (often above Target for pricing headroom). -- **Confidence** — how tightly you price around that expectation (**High / Normal / Wide** — not an uptime %). +- **Claim** — the reliability level you believe your machine will deliver (shown to clients as `expected_reliability`). +- **Confidence** — how tightly you price around that claim (`sla_sigma_x`; lower = tighter / cheaper for clients at a given target). -The API field names and backtester aliases below are for automation. Skip them if you use the web console only. +Clients choose their own **reliability target** at search and rent time. You do **not** set the client target on the listing. -Think of an SLA offer as three linked ideas: +Think of an SLA offer as two host ideas plus one client choice: -1. **Reliability target** — the uptime level the listing is priced around (for example, 95% or 99%). -2. **Your reliability claim** — what you believe your machine will actually deliver. -3. **Your confidence** — how sure you are about that claim. Tight confidence means you stand behind a narrow range; wide confidence means a wider defensible range and clients pay a higher premium. +1. **Your reliability claim** — what you believe your machine will deliver (`sla_r_claim`). Setting this above `0` enables SLA on the offer. +2. **Your confidence** — how wide your belief is around that claim (`sla_sigma_x`). Tighter confidence → lower SLA charges for clients at a given target; wider confidence → higher charges. +3. **Client reliability target** — chosen by the renter via search (`target_reliability`). Settlement and SLA charge sizing use this target. Clients typically pick a target **at or below** your claim. -**Claim headroom:** Set **Claim** higher than **Target** unless you intentionally want higher client premiums. Clients pay based on the gap between claim and target; payouts still use **Target**. Example: Target 95%, Claim 99%. +When a client rents an on-demand instance on your SLA-listed offer with a chosen target: -When a client rents an on-demand instance on your SLA-listed offer, Vast measures uptime against your published target and claim percentages: +- They pay **compute** (GPU, storage, bandwidth) plus a **small hourly SLA charge** included in `dph_total`. +- Each UTC calendar day, Vast measures reliability for the contract and settles the SLA. +- **Strong reliability relative to the client's target** → you keep the SLA charge for that day. +- **Shortfalls** → credits flow to the client from your earnings (bounded by that day's covered compute). -- They pay **compute** (GPU, storage, bandwidth) plus a **small hourly SLA add-on** included in `dph_total`. -- Each UTC calendar day, Vast measures how long the instance was online and settles the SLA. -- **Good uptime** → you keep the premium for that day. -- **Bad uptime** → you pay the client from your earnings (up to the day's compute revenue). +Over many strong days, SLA charges can offset occasional credits, but a single bad day can exceed months of collected charges — see [Risk scenarios](#risk-scenarios) and `worst_day_loss` before you commit. -Over many good-uptime days, premiums can offset occasional payouts, but a single bad day can exceed months of collected premiums — see [Risk scenarios](#risk-scenarios) and `worst_day_loss` before you commit. +### How reliability is measured -### How uptime is measured +SLA reliability is measured at the **rental contract (instance) level** using platform health signals for active on-demand contracts — not your personal SSH session or Jupyter tab. -SLA uptime is measured at the **rental contract (instance) level** using platform health signals for active on-demand contracts — not your personal SSH session or Jupyter tab. - -- **Instance fails to start** when a client rents → counts against SLA uptime for that contract. +- **Instance fails to start** when a client rents → counts against SLA reliability for that contract. - **Machine-level outage** while contracts are active → affects settlement for those contracts. -- **Brief host reboots** during active rentals may count as downtime if they exceed the platform's measurement window for that UTC day. Vast does not publish a fixed second-level threshold in host docs — treat unplanned reboots as SLA risk. For planned work, use [Scheduled maintenance](#scheduled-maintenance) with at least 24 hours' notice when possible. +- **Brief host reboots** during active rentals may count as downtime. Vast does not publish a fixed second-level threshold in host docs — treat unplanned reboots as SLA risk. For planned work, use [Scheduled maintenance](#scheduled-maintenance) with at least 24 hours' notice when possible. - **Scheduled maintenance** may receive credit case by case — see [Scheduled maintenance](#scheduled-maintenance). On sliced machines, SLA settles **per rental contract**. If one GPU slice fails but others remain healthy, only contracts on the affected slice are measured for downtime. +### Billing vs settlement (important) + +For SLA-covered on-demand contracts, compute billing uses the **intended daily compute** for the rental. Offline time is tracked as an outage in reliability observations. Client compensation for poor reliability flows through **SLA settlement credits**, not by silently zeroing the day's compute bill. + ## SLA parameters When you list or update a machine, set SLA fields via the host console or `PUT /api/v0/machines/create_asks/` (see [Listing an SLA offer](#listing-an-sla-offer) below). | Parameter | API field | Backtester alias | What it means | | --- | --- | --- | --- | -| Reliability target | `sla_r_target` | `r` | The uptime level the offer is priced around. Set above `0` to enable SLA. Values are greater than 0 and at most **0.9999** (for example, `0.95` = 95%). Exactly `1.0` is rejected. Legacy alias: `sla_reliability` (deprecated; use `sla_r_target` instead). If both are sent, `sla_r_target` takes precedence. | -| Reliability claim | `sla_r_claim` | — (backtester sets claim = target) | Your advertised belief about machine uptime. Defaults to the reliability target if omitted. Must be **≥** the target. Same bounds as target (greater than 0, at most 0.9999). | -| Confidence spread | `sla_sigma_x` | `p` (different scale — see [backtester](/host/sla-backtester#confidence-values-p)) | How wide your belief is around the claim. Lower = more confident (cheaper for clients). Defaults to `0.5` if omitted. | +| Reliability claim | `sla_r_claim` | `r` (backtester sets claim = target = `r`) | Your advertised belief about machine reliability. Set above `0` to enable SLA. Values are greater than 0 and at most **0.9999** (for example, `0.99` = 99%). Exactly `1.0` is rejected. Set to `0` to disable SLA on new rentals. | +| Confidence spread | `sla_sigma_x` | `p` (different scale — see [backtester](/host/sla-backtester#confidence-values-p)) | How wide your belief is around the claim. Lower = more confident (lower SLA charges for clients at a given target). Defaults to `0.5` if omitted. | +| Max client β (optional) | `sla_max_beta` | — | Advanced term capping how path-dependent a client's timescale mix can be. Most hosts can omit this. Must be in `(0, 1)` and at least the default β derived at your claim. | -Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x`. They use different scales. Use the preset mapping table below (for example, Normal → `sla_sigma_x=0.5`, which corresponds to backtester `p=0.6667`). +**`sla_r_target` is not host-settable.** If you send `sla_r_target` or legacy `sla_reliability` on `create_asks/`, they are **ignored**. Clients supply their coverage target at search/rent time (`target_reliability`). Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x` — they use different scales. Use the mapping table on the [backtester page](/host/sla-backtester#confidence-values-p). -| Concept | Console | Listing API | Backtester | Client sees | +| Concept | Console | Listing API | Backtester | Client sees / sets | | --- | --- | --- | --- | --- | -| Reliability target | Target | `sla_r_target` | `r` | Target % (coverage level) | -| Reliability claim | Claim | `sla_r_claim` | (set equal to target in backtester) | — | -| Confidence | Confidence | `sla_sigma_x` | `p` (different scale — do not copy directly) | — | -| All-in hourly price | — | — | — | `dph_total` (dollars per hour total in search — compute plus SLA premium when enabled) | - -**Confidence is not an uptime target.** It controls how aggressively premiums are priced around your claim. - +| Reliability claim | Claim | `sla_r_claim` | `r` (claim = target in sim) | `expected_reliability` | +| Confidence | Confidence / spread | `sla_sigma_x` | `p` (different scale) | — | +| Reliability target | — (client-chosen) | — (not on asks) | `r` (same as claim in sim) | `target_reliability` in search | +| All-in hourly price | — | — | — | `dph_total` (compute plus SLA charge when enabled) | - -**Confidence in one sentence:** The **preset name** (High / Normal / Wide) controls how **tightly premiums are priced around the uptime level you claim you will deliver** (your claim), not around the published reliability target clients see in search. In the console, use the labeled presets rather than raw numbers. The ~83% figure applies to the **High** preset — it describes how often your machine's actual uptime is expected to meet or exceed your claim, not the target percentage itself. +**Confidence is not an uptime target.** It controls how aggressively SLA charges are priced around your claim. -### Machine reliability score vs SLA uptime +### Machine reliability score vs SLA reliability -The **reliability score** on the Host Machines page reflects connection and instance-start behavior (and is earnings-weighted). **SLA settlement** measures whether covered instances met your published uptime target for billing purposes. +The **reliability score** on the Host Machines page reflects connection and instance-start behavior (and is earnings-weighted). **SLA settlement** measures whether covered instances met the client's published uptime target for billing purposes. -Do not assume the dashboard score equals SLA uptime. Before choosing `sla_r_target`: +Do not assume the dashboard score equals SLA reliability. Before choosing `sla_r_claim`: -1. Open **Host → Machines** → **Set Pricing → SLA** and review the console premium preview at candidate targets. +1. Open **Host → Machines** → **Set Pricing → SLA** and review the console SLA charge preview at candidate claims. 2. If you have rental history, run the [backtester](/host/sla-backtester) and check top-level `reliability` in the response. -3. Set **target** at or slightly below the uptime level you can sustain; use **claim above target** for competitive premiums. +3. Set **claim** at a level you can sustain; clients who pick targets below your claim see lower SLA charges. -### Confidence presets +### Confidence values -**This only changes how SLA premiums are priced — it does not change how uptime is measured or what payout you owe.** Use the **High / Normal / Wide** presets in the console UI. Only set raw `sla_sigma_x` via the API if you need a value outside those presets. +**This only changes how SLA charges are priced — it does not change how reliability is measured or what credit you owe when a client's target is missed.** Prefer the console controls. Set raw `sla_sigma_x` via the API when automating. - -Confidence presets control **pricing weight only**, not your uptime obligation. Your obligation is set by **Target**. The statistical weights in the table below (~83% / ~67% / ~50%) describe pricing confidence — do not treat them as uptime targets. - - -| Preset | Pricing effect | `sla_sigma_x` | Risk if you miss claim | +| Guidance | Pricing effect | `sla_sigma_x` | Risk if you miss claim | | --- | --- | --- | --- | -| **High** | Tightest pricing (lowest client premiums) | `0.2` | Highest premium sensitivity | -| **Normal** (default) | Balanced | `0.5` | Moderate | -| **Wide** | Widest pricing band | `1.0` | Lowest premium sensitivity | +| Tight | Lowest client SLA charges at a given target | `0.2` | Highest charge sensitivity | +| Normal (default) | Balanced | `0.5` | Moderate | +| Wide | Highest client SLA charges at a given target | `1.0` | Lowest charge sensitivity | -Higher preset confidence (tighter spread) → lower client premiums, but less room for uptime to slip before payouts. +Higher confidence (tighter spread) → lower client SLA charges, but less room for reliability to slip before settlement credits grow. ### Validation rules Offers with invalid combinations are rejected at listing time: -- The reliability target must be greater than 0 and at most **0.9999** when enabling SLA. Set to `0` to disable SLA. -- The reliability claim must be greater than 0, at most **0.9999**, and must be **≥** the target. -- Confidence spread must be positive and at most `3.0`. +- `sla_r_claim` must be `0` (disable) or greater than 0 and at most **0.9999**. Exactly `1.0` is rejected. +- When claim is positive, `sla_sigma_x` must be positive and at most `3.0` (defaults to `0.5` if omitted). +- Optional `sla_max_beta` must be in `(0, 1)` and at least the default β derived at your claim. -If listing is rejected with `error: "invalid_sla_params"`, check the `msg` field against the rules above. Common causes: claim below target, `sla_sigma_x` out of range, values of exactly `1.0`, or invalid partial-update combinations. +If listing is rejected with `error: "invalid_sla_params"`, check the `msg` field against the rules above. Other SLA listing errors include `sla_not_approved` and `sla_daemon_outdated`. ### SLA and GPU slicing -SLA settlement applies per rental contract. If your machine has multiple GPU slices rented by different clients (GPU slicing — see **Min GPU** in [Hosting Overview](/host/hosting-overview)), each contract's SLA is settled independently based on the uptime experienced by that instance. +SLA settlement applies per rental contract. If your machine has multiple GPU slices rented by different clients (GPU slicing — see **Min GPU** in [Hosting Overview](/host/hosting-overview)), each contract's SLA is settled independently based on the reliability experienced by that instance. The backtester replays **machine-level** daily earnings (total compute across all active rentals on that machine). `worst_day_loss` in `summary` reflects the worst simulated day for the whole machine in the replay window — not a single GPU slice in isolation. On sliced machines, a full-machine outage can affect every concurrent SLA rental at once. Use `worst_day_loss` as your primary tail-risk metric for the machine, and sanity-check exposure against how many SLA-covered instances you typically run in parallel. Do **not** multiply `worst_day_loss` by contract count — the backtester already models machine-level compute for the replay window. -To see how many rentals are active on a machine, check the [Host Machines page](https://cloud.vast.ai/host/machines) or run `vastai show machines` and inspect the rented/active instance fields for that `machine_id`. - ### SLA on extended contracts When a rental contract is extended (by moving the offer end date forward at the same or lower price), the original SLA parameters remain in effect for the extended period. Changing SLA parameters on the offer does not alter SLA terms on existing contracts — only new rental contracts pick up updated SLA settings. -Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-covered contracts but does not terminate SLA on existing active contracts — they continue under their original SLA terms until their rental end date. +Disabling SLA on the offer (setting `sla_r_claim` to `0`) prevents new SLA-covered contracts but does not terminate SLA on existing active contracts — they continue under their original SLA terms until their rental end date. ## Listing an SLA offer @@ -174,17 +161,17 @@ Disabling SLA on the offer (setting `sla_r_target` to `0`) prevents new SLA-cove 1. Open your machine on the [Host Machines page](https://cloud.vast.ai/host/machines) → **Set Pricing**. 2. Set base listing fields first (GPU price, offer end date, rental types) if this is a new listing. 3. Expand **SLA**. -4. Set **Reliability target**, **Reliability claim**, and **Confidence** (or a preset). Set **Claim** higher than **Target** (for example, 99% claim / 95% target) unless you want higher premiums. -5. Save and confirm the SLA premium preview before listing. +4. Set **Claim** and **Confidence** (spread). Example: claim **99%** with normal confidence. +5. Save and confirm the SLA charge preview before listing. 6. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. #### Updating SLA on an already-listed machine -If the machine is already **listed** (you previously clicked **LIST** or listed via CLI/REST): +If the machine is already **listed**: -1. Open **Host → Machines → Set Pricing → SLA**, set Target, Claim, and Confidence, then click **Save**. +1. Open **Host → Machines → Set Pricing → SLA**, set Claim and Confidence, then click **Save**. 2. **Save** applies SLA to the live offer — you do not need to click **LIST** again unless this is a brand-new listing that was never published. -3. Verify in search: `dph_total` includes the SLA add-on and `expected_reliability` matches your Target (see [Search / client-visible fields](#search--client-visible-fields)). +3. Verify in search: `dph_total` includes the SLA charge at a client's `target_reliability`, and `expected_reliability` matches your claim (see [Search / client-visible fields](#search--client-visible-fields)). In the web console, **Set Pricing → Save** stores SLA settings; clicking **LIST** publishes the offer to search. `PUT /api/v0/machines/create_asks/` performs both steps in one request — it creates or updates the **live listing** (same as pressing **LIST** or running `vastai list machine`), not a save-only draft. @@ -192,7 +179,7 @@ In the web console, **Set Pricing → Save** stores SLA settings; clicking **LIS #### Web console SLA preview -In the host console, open **Host Machines** → select your machine → **Set Pricing** → **SLA**. The preview shows estimated SLA premium and payout exposure for the parameters you enter. It is a forward-looking quote, not a historical replay — use the [SLA Backtester](/host/sla-backtester) for history-based simulation. +In the host console, open **Host Machines** → select your machine → **Set Pricing** → **SLA**. The preview shows estimated SLA charge and payout exposure for the parameters you enter. It is a forward-looking quote, not a historical replay — use the [SLA Backtester](/host/sla-backtester) for history-based simulation. ### API (for automation) @@ -204,17 +191,11 @@ SLA listing via `vastai list machine` and `VastAI.list_machine()` is **not yet a #### Before you start -SLA listing requires the REST API today — CLI and SDK SLA flags are not yet available in published tooling. - -Before you call this endpoint, your machine must appear on **Host → Machines** with the daemon connected. This call creates or updates the **offer**, not machine registration. See [Host setup](https://cloud.vast.ai/host/setup/). - 1. Open **Account → API Keys** and create a key. See [Create API Key](/api-reference/accounts/create-api-key). -2. For listing SLA offers, enable **`machine_write`**. For backtesting first, add **`machine_read`**. For post-listing earnings, add **`billing_read`** (one key can include multiple permissions). +2. For listing SLA offers, enable **`machine_write`**. For backtesting first, add **`machine_read`**. For post-listing earnings, add **`billing_read`**. 3. Use the key as `Authorization: Bearer YOUR_API_KEY` in the `curl` examples below. See [Authentication](/api-reference/authentication). -4. To enable SLA today, use `PUT /api/v0/machines/create_asks/` or **Set Pricing → SLA** in the console. `vastai list machine` hits the same endpoint for non-SLA fields only until CLI SLA flags ship. The listing body field is `machine` (same ID as backtester `machine_id` and earnings `machid`). -5. For the full request/response schema (including `sla_r_target`, `sla_r_claim`, `sla_sigma_x`, and `invalid_sla_params`), see [List Machine](/api-reference/machines/list-machine). - -Listing or updating SLA parameters requires an API key with **`machine_write`** permission. Backtesting requires **`machine_read`**. See [API permissions](/api-reference/permissions). +4. To enable SLA today, use `PUT /api/v0/machines/create_asks/` or **Set Pricing → SLA** in the console. The listing body field is `machine` (same ID as backtester `machine_id` and earnings `machid`). +5. For the full request/response schema, see [List Machine](/api-reference/machines/list-machine). The example below **adds SLA to an offer that already has base pricing configured**. For a first-time listing, include all required base fields (`price_gpu`, `end_date`, `min_chunk`, storage/bandwidth prices as needed) — see [Hosting overview](/host/hosting-overview#offers-and-rental-contracts). @@ -227,7 +208,6 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -d '{ "machine": 12345, "price_gpu": 3.50, - "sla_r_target": 0.95, "sla_r_claim": 0.99, "sla_sigma_x": 0.5, "end_date": 1735689600 @@ -238,32 +218,27 @@ Set `end_date` so the offer does not stay open indefinitely — especially impor Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). -Minimal example (includes recommended claim headroom): +Minimal example: ```json { "machine": 12345, "price_gpu": 3.50, "end_date": 1735689600, - "sla_r_target": 0.95, "sla_r_claim": 0.99, "sla_sigma_x": 0.5 } ``` - -Setting only `sla_r_target` defaults `sla_r_claim` to the same value, which increases client premiums. For better economics, set **claim above target** (for example, target 95%, claim 99%). - - -This creates an offer with target `0.95`, claim `0.99`, and confidence spread `0.5`. +This creates an offer with claim `0.99` and confidence spread `0.5`. Clients who search with `target_reliability` below your claim see lower SLA charges than clients who ask for coverage near your claim. -Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_target` to `0` to disable SLA on an existing listing. +Partial updates are supported when editing an existing listing. If you change only one SLA field, the platform re-validates the merged parameters. Set `sla_r_claim` to `0` to disable SLA on an existing listing. -Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. Read current listing fields from `vastai show machines --raw` (filter with `jq` below). See [Show Machines](/api-reference/machines/show-machines) for the documented REST response shape: +Omitted non-SLA fields retain their current listing values; only fields present in the request body are updated. Read current listing fields from `vastai show machines --raw`: ```bash -vastai show machines --raw | jq '.machines[] | select(.id == 12345 or .id == "12345") | {id, sla_r_target, sla_r_claim, sla_sigma_x, price_gpu, end_date}' +vastai show machines --raw | jq '.machines[] | select(.id == 12345 or .id == "12345") | {id, sla_r_claim, sla_sigma_x, price_gpu, end_date}' ``` Machine `id` may be a string in raw JSON. The response is wrapped in a `machines` array. @@ -277,7 +252,7 @@ For multiple machines, loop sequentially — do not parallelize without backoff: 1. `PUT /api/v0/machines/create_asks/` with `machine` plus SLA fields and required base pricing. 2. On `429`, sleep and retry with exponential backoff. -3. On `invalid_sla_params` or `machine_locked`, log the machine ID and continue or abort per your rollout policy. +3. On `invalid_sla_params`, `sla_not_approved`, `sla_daemon_outdated`, or `machine_locked`, log the machine ID and continue or abort per your rollout policy. See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for a similar sequential pattern. @@ -286,7 +261,7 @@ export VAST_API_KEY="YOUR_API_KEY" machines=$(vastai show machines --raw) for id in $(vastai show machines -q); do body=$(echo "$machines" | jq -c --arg id "$id" \ - '.machines[] | select((.id|tostring) == $id) | {machine: (.id|tonumber), price_gpu, end_date, min_chunk, sla_r_target: 0.95, sla_r_claim: 0.99, sla_sigma_x: 0.5}') + '.machines[] | select((.id|tostring) == $id) | {machine: (.id|tonumber), price_gpu, end_date, min_chunk, sla_r_claim: 0.99, sla_sigma_x: 0.5}') resp=$(curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -H "Authorization: Bearer $VAST_API_KEY" \ -H "Content-Type: application/json" \ @@ -304,10 +279,10 @@ Fetch the fleet once before the loop — do not call `show machines --raw` insid curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ - -d '{"machine": 12345, "sla_r_target": 0.99, "sla_r_claim": 0.995, "sla_sigma_x": 2.0}' + -d '{"machine": 12345, "sla_r_claim": 0.995, "sla_sigma_x": 0.2}' ``` -**Disable SLA on new rentals** — set `sla_r_target` to `0` (active contracts keep their terms). +**Disable SLA on new rentals** — set `sla_r_claim` to `0` (active contracts keep their terms). #### Common errors @@ -317,6 +292,8 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ | 403 | `machine_locked` | Machine is decommissioned or migration-locked | | 400 | `invalid_args` | Machine ID not found for your account (includes other hosts' machines) | | 400 | `invalid_sla_params` | SLA parameters failed validation | +| 400 | `sla_not_approved` | Host account is not approved to create SLA asks | +| 400 | `sla_daemon_outdated` | Machine daemon build is too old for SLA listing | | 400 | `invalid_args` | Malformed or incompatible request body | **`machine_locked`:** Returned when a machine is decommissioned or migration-locked. If you are migrating hardware, finish or cancel active rentals first, remove or update the listing as needed, and contact support if the machine remains locked. Existing SLA terms on active contracts remain in force until those contracts end. @@ -344,108 +321,100 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ ## Economics walkthrough -**Setup:** You list an H100 at **$3.50/hr** GPU price with target **95%**, claim **99%**, and normal confidence (`sla_sigma_x = 0.5`). +**Setup:** You list an H100 at **$3.50/hr** GPU price with claim **99%** and normal confidence (`sla_sigma_x = 0.5`). A client searches with **target 95%**. | Item | Amount | | --- | --- | | Daily compute (`C`) | ~$84/day ($3.50 × 24 hr GPU only — simplified) | -| SLA premium (client pays) | ~**$0.008/hr** (~$0.20/day at 24 hr) | +| SLA charge (client pays) | ~**$0.008/hr** (~$0.20/day at 24 hr) | -SLA payouts are capped at that UTC day's total billable earnings — GPU, storage, and bandwidth combined — not GPU compute alone. The simplified example below uses GPU-only math for readability; treat `worst_day_loss` from the [SLA backtester](/host/sla-backtester) as the authoritative tail-risk figure before you list. +SLA credits are capped relative to that UTC day's covered compute — GPU, storage, and bandwidth combined — not GPU compute alone. The simplified example below uses GPU-only math for readability; treat `worst_day_loss` from the [SLA backtester](/host/sla-backtester) as the authoritative tail-risk figure before you list. -Premium sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst single-day payout exposure (`worst_day_loss`), not exact client premiums. For authoritative client-visible premiums, use **Set Pricing → SLA** in the console or **`dph_total`** in search offers — not backtester `total_sla` when claim exceeds target. +SLA charge sizing uses internal SLA math. Use the [SLA backtester](/host/sla-backtester) to preview worst single-day credit exposure (`worst_day_loss`), not exact client SLA charges. For authoritative client-visible charges, use **Set Pricing → SLA** in the console or **`dph_total`** in search offers at a chosen `target_reliability` — not backtester `total_sla` when clients will rent below your claim. -The economics above assume **claim above target** (headroom): claim (99%) is above target (95%), so clients see lower premiums than if both matched. The [backtester](/host/sla-backtester) cannot simulate claim headroom — it sets claim equal to target — so its simulated premiums will be higher. Use `worst_day_loss` from the backtester as your worst single-day payout reference, then verify visible premiums in **Set Pricing → SLA** (or `dph_total` in search) before listing with claim above target. +The backtester sets claim equal to target (`r`), which is a **conservative** what-if (as if every client targeted your claim). Live clients who choose targets **below** your claim usually see lower SLA charges than the backtester's simulated charges. Use `worst_day_loss` from the backtester as your worst single-day credit reference, then verify visible charges in **Set Pricing → SLA** (or `dph_total` in search) before listing. -This premium is what a client searching for 95% reliability would see added to the total hourly price in search results (`dph_total` — visible in the console SLA preview or [Search Offers](/api-reference/search/search-offers) results). - ### Search / client-visible fields When SLA is enabled on an offer, clients see: -- **`dph_total`** — total $/hour including the SLA premium (authoritative for client-visible all-in pricing). -- **`expected_reliability`** — the advertised SLA target (maps to your `sla_r_target`). -- **`reliability` / `reliability2`** — historical machine reliability scores, **not** your SLA target. +- **`dph_total`** — total $/hour including the SLA charge at their `target_reliability` (authoritative for client-visible all-in pricing). +- **`expected_reliability`** — your advertised claim (maps to `sla_r_claim`). +- **`reliability` / `reliability2`** — historical machine reliability scores, **not** your SLA claim. -**Filter vs response field:** In search queries, the `reliability` filter uses the machine's historical reliability score — not the SLA target. The published SLA target appears in responses as `expected_reliability`. To select SLA-listed offers programmatically, post-filter on `expected_reliability > 0` (or your minimum target); do not use the `reliability` filter as an SLA selector. +**Filter vs response field:** In search queries, the `reliability` filter uses the machine's historical reliability score — not the SLA claim. The published SLA claim appears in responses as `expected_reliability`. To select SLA-listed offers programmatically, use `has_sla=true` or filter on `expected_reliability > 0`; do not use the `reliability` filter as an SLA selector. Verify after listing — filter the offer you care about; sliced machines often return multiple rows (different `num_gpus`, bid vs on-demand): ```bash -vastai search offers 'machine_id=12345 verified=any' --raw \ +vastai search offers 'machine_id=12345 verified=any has_sla=true target_reliability=0.95' --raw \ | jq '[.offers[] | select(.is_bid == false) | {id, num_gpus, dph_total, expected_reliability, reliability}]' ``` -Premium sizing uses internal SLA math — use the console preview or `dph_total` above, not backtester `total_sla`, when claim exceeds target. - -### If you meet your claim +### If reliability is strong relative to the client's target -In the **You net** column, values follow host earnings sign conventions: positive means premium you kept; negative means payout you owed the client. +In the **You net** column, values follow host earnings sign conventions: positive means SLA charge you kept; negative means credit you owed the client. -| Measured uptime (simplified) | You net (per day) | +| Measured reliability (simplified) | You net (per day) | | --- | --- | -| ~100% (excellent day) | +$0.20 (keep premium) | -| ~99% (good day) | +$0.17 (keep premium) | +| ~100% (excellent day) | +$0.20 (keep SLA charge) | +| ~99% (good day) | +$0.17 (keep most of the SLA charge) | -You keep most or all of the premium. +You keep most or all of the SLA charge. -### What if measured uptime is between my target and my claim? +### What if measured reliability is between the client's target and my claim? -Example: you publish **target 95%**, claim **99%**, and measured uptime is **~97%**. +Example: you publish **claim 99%**, the client chose **target 95%**, and measured reliability is **~97%**. -- **Payouts** are evaluated against your published **target** (95%), not your claim. -- Because 97% is above 95%, you typically **owe no SLA payout** for that day. -- **Premiums** are priced from your **claim** (99%) and confidence — a higher claim generally means lower client premiums. +- **Credits** are evaluated against the client's **target** (95%), not your claim. +- Because 97% is above 95%, you typically **owe no SLA credit** for that day. +- **SLA charges** are priced from your **claim**, confidence, and the client's target — a higher claim relative to the target generally means lower client charges. -**Claim** is mainly a pricing knob; **target** is what clients see and what drives payout eligibility. +**Claim** is your belief/pricing knob; the client's **target** is what drives payout eligibility. -### If you miss the target +### If the client's target is missed -Payouts scale relative to the day's compute revenue, not the premium collected. A single bad day at your target boundary can cost as much as 200+ days of collected premiums. Review the economics below and run the [backtester](/host/sla-backtester) before enabling SLA. +Credits scale relative to the day's compute, not only the SLA charge collected. A single bad day near the client's target boundary can cost as much as 200+ days of collected SLA charges. Review the economics below and run the [backtester](/host/sla-backtester) before enabling SLA. - -Visible client premiums are lower than backtester output when `sla_r_claim` is above `sla_r_target`. Use `worst_day_loss` as your worst single-day payout reference. The table below illustrates payout at the target boundary only. - +These scenarios show settlement when reliability **drops to or below** a 95% client target — they are boundary illustrations, not typical strong days: -These scenarios show settlement when uptime **drops to or below** the target — they are boundary illustrations, not typical good-uptime days. Payouts for brief outages may be **smaller than the worst-case table** shown below; exact settlement depends on measured uptime for the UTC day and active contract terms: - -| Measured uptime (simplified) | You net (per day) | +| Measured reliability (simplified) | You net (per day) | | --- | --- | -| At target (~95%) | −$42 (payout you owe) | -| Well below target (~90% or less) | −$84 (full compute refund owed) | +| At target (~95%) | −$42 (credit you owe) | +| Well below target (~90% or less) | −$84 (large credit owed) | -To put the asymmetry in perspective: at ~$0.20/day in premiums, it takes roughly 210 good days to accumulate the $42 you could lose on a single day at the target boundary. The premium is a small fraction of daily compute, while the payout scales against total daily compute revenue. +To put the asymmetry in perspective: at ~$0.20/day in SLA charges, it takes roughly 210 strong days to accumulate the $42 you could lose on a single day at the target boundary. The SLA charge is a small fraction of daily compute, while credits scale against total daily compute. -On a severe outage day, the client is made whole on compute charges for that day. You do not collect the premium for that day either — the client is not charged a premium on top of compute charges for periods when the instance was down. Your maximum SLA loss on any single settlement day is capped at that day's total billable earnings (GPU, storage, and bandwidth). +Your maximum SLA loss on any single settlement day is bounded by that day's covered compute (GPU, storage, and bandwidth). ## Risk scenarios -### You claim 99% but deliver 99.5% +### You claim 99% and deliver 99.5% -You outperform your claim. Clients pay small premiums; payouts are rare. You net positive on SLA over time. +You outperform your claim. Clients who chose targets at or below 99% pay small SLA charges; credits are rare. You net positive on SLA over time. ### You claim 99% but have an offline day -Clients receive payouts tied to how far measured uptime falls below the target. Extended outages can approach a full-day compute refund. Your reliability score and verification status may also be affected separately from SLA settlement. +Clients receive credits tied to how far measured reliability falls below **their** target. Extended outages can approach a full-day compute credit. Your reliability score and verification status may also be affected separately from SLA settlement. -### You set target equal to claim (for example, both 95%) +### Clients target near your claim -Premiums are **much higher** because you are not offering any headroom — you are not setting **claim above target**. Clients only buy this when they need coverage exactly at your stated level. Prefer setting **claim above target** (for example, claim 99%, target 95%) for competitive premiums. +SLA charges are **much higher** when the client's target sits near your claim (little headroom). Prefer a claim you can sustain above the targets clients actually choose. ### You widen confidence (`sla_sigma_x` → 1.0) -Clients pay more because you admit greater uncertainty. Use this if your uptime history is volatile or the machine is new. +Clients pay more because you admit greater uncertainty. Use this if your reliability history is volatile or the machine is new. ### Scheduled maintenance -Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) may be credited back toward uptime, reducing SLA penalties for planned downtime. Unplanned outages count fully toward SLA settlement. +Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) may be credited back toward reliability, reducing SLA penalties for planned downtime. Unplanned outages count fully toward SLA settlement. -Planned maintenance credit is not guaranteed. The platform evaluates advance notice (generally at least 24 hours recommended) and maintenance duration when determining credit eligibility. **Treat any scheduled downtime as a potential SLA payout event when modeling risk.** Contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or email [contact@vast.ai](mailto:contact@vast.ai) before extended maintenance on an SLA-listed machine to confirm credit eligibility. +Planned maintenance credit is not guaranteed. The platform evaluates advance notice (generally at least 24 hours recommended) and maintenance duration when determining credit eligibility. **Treat any scheduled downtime as a potential SLA credit event when modeling risk.** Contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or email [contact@vast.ai](mailto:contact@vast.ai) before extended maintenance on an SLA-listed machine to confirm credit eligibility. ## Preview earnings before listing @@ -454,26 +423,27 @@ Use the [SLA Earnings Backtester](/host/sla-backtester) (API-only; requires a `m ## When things go wrong -- **Listing rejected (`invalid_sla_params`)** — Re-check target, claim, and `sla_sigma_x` against [validation rules](#validation-rules). -- **Unexpected payout** — Review uptime; re-run the backtester with a low `reliability` stress value (for example `0.01`). -- **Severe outage** — Disable SLA on new contracts: open **Host → Machines** → **Set Pricing → SLA**, set target to `0` (or use API `sla_r_target=0`); contact [Discord](https://discord.gg/hSuEbSQ4X8) before relisting. +- **Listing rejected (`invalid_sla_params`)** — Re-check claim and `sla_sigma_x` against [validation rules](#validation-rules). +- **`sla_not_approved` / `sla_daemon_outdated`** — Contact support or update the daemon from the host setup page. +- **Unexpected credit** — Review reliability; re-run the backtester with a low `reliability` stress value (for example `0.01`). +- **Severe outage** — Disable SLA on new contracts: open **Host → Machines** → **Set Pricing → SLA**, set claim to `0` (or use API `sla_r_claim=0`); contact [Discord](https://discord.gg/hSuEbSQ4X8) before relisting. ## Monitoring SLA after listing -After you enable SLA, premiums and payouts settle on UTC (Coordinated Universal Time) day boundaries. SLA earnings rows typically appear in **Host → Billing** within a few hours after UTC midnight (exact timing can vary). +After you enable SLA, charges and credits settle on UTC (Coordinated Universal Time) day boundaries. SLA earnings rows typically appear in **Host → Billing** within a few hours after UTC midnight (exact timing can vary). ### Console (recommended for day-to-day checks) 1. Go to **Host → Billing** (or **Earnings** / **Reports**). 2. Set the date range to include the UTC day you want to review. 3. Filter by machine ID if available. -4. Look for **SLA** entries in the earnings breakdown — positive amounts are premiums you kept; negative amounts are payouts you owed the client. +4. Look for **SLA** entries in the earnings breakdown — positive amounts are SLA charges you kept; negative amounts are credits you owed the client. 5. After downtime, compare the affected UTC day(s) to your `worst_day_loss` backtest estimate. **If you don't see SLA rows:** widen the date range (settlement uses UTC day boundaries), confirm the machine had an active on-demand rental that day, and confirm SLA was enabled and the offer was **listed** (not just saved). -SLA daily settlement (premium kept / payout owed) does not currently emit host webhooks. Monitor via console billing or poll `machine-earnings`; settlements align to UTC calendar days. +SLA daily settlement (SLA charge kept / credit owed) does not currently emit host webhooks. Monitor via console billing or poll `machine-earnings`; settlements align to UTC calendar days. ### CLI @@ -499,14 +469,7 @@ vastai show earnings --machine_id --start_date $(date -u -d 'yesterday' +%F | jq '.per_machine[] | select(.machine_id == or .machine_id == "") | {machine_id, sla_earn}' ``` -**Linux (GNU date) — seven-day window (do not compare directly to single-day `worst_day_loss`):** - -```bash -vastai show earnings --machine_id --start_date $(date -u -d '7 days ago' +%F) --end_date $(date -u +%F) --raw \ - | jq '.per_machine[] | select(.machine_id == or .machine_id == "") | {machine_id, sla_earn}' -``` - -Positive `sla_earn` = net SLA premium you kept that period; negative = net payout you owe. Weekly aggregates are window totals, not daily series — use a one-day range above for day-level checks. +Positive `sla_earn` = net SLA charge you kept that period; negative = net credit you owe. Weekly aggregates are window totals, not daily series — use a one-day range above for day-level checks. ### API (automation) @@ -522,17 +485,15 @@ Positive `sla_earn` = net SLA premium you kept that period; negative = net payou | List or update SLA on an offer | `machine_write` | | Post-listing SLA earnings | `billing_read` | -For API automation only — console users can stop after the Console subsection above. +`GET /api/v0/users/{user_id}/machine-earnings/` returns SLA fields alongside compute earnings. Requires a **`billing_read`** API key. See [`show earnings`](/api-reference/billing/show-earnings). -`GET /api/v0/users/{user_id}/machine-earnings/` returns SLA fields alongside compute earnings. Requires a **`billing_read`** API key (separate from `machine_read` used for the backtester). See [`show earnings`](/api-reference/billing/show-earnings). - -This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request every two seconds per IP (`threshold=2.0`); back off on HTTP 429. For day-level per-machine reconciliation at scale, prefer console billing reports over high-frequency API polling. +This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request every two seconds per IP (`threshold=2.0`); back off on HTTP 429. -When you pass `machid`, use `per_machine[].sla_earn` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. Do not assume `summary.total_sla` is machine-scoped when `machid` is set — prefer `per_machine[].sla_earn`. +When you pass `machid`, use `per_machine[].sla_earn` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. **Quick rules:** -- **One machine, one UTC day:** use `last_days=1` with `machid` set, or `sday`/`eday` (UTC day indices). The CLI flags `--start_date` and `--end_date` map internally to those fields — they are not separate REST query parameter names on `machine-earnings/`. +- **One machine, one UTC day:** use `last_days=1` with `machid` set, or `sday`/`eday` (UTC day indices). - **Fleet snapshot:** one request without `machid` returns all machines in `per_machine[]` for the window: ```bash @@ -540,8 +501,6 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/users/{user_id}/machine-earnings/?last_days=1" \ | jq '.per_machine[] | {machine_id, sla_earn}' ``` - -Poll no faster than about one request every two seconds. Prefer console billing exports for month-end reconciliation. **Machine-scoped one-day total:** @@ -556,27 +515,25 @@ Do **not** compare `last_days=7` totals to single-day `worst_day_loss` from the **Sign convention** (same as backtester `sla` / `historical_sla`): -| Field | Good day (meet target) | Bad day (miss target) | +| Field | Strong day (meet client target) | Weak day (miss client target) | | --- | --- | --- | -| `per_machine[].sla_earn` | Positive (premium kept) | Negative (payout you owe) | -| Fleet `per_day[].sla_earn` | Positive (premium kept) | Negative (payout you owe) | +| `per_machine[].sla_earn` | Positive (SLA charge kept) | Negative (credit you owe) | +| Fleet `per_day[].sla_earn` | Positive (SLA charge kept) | Negative (credit you owe) | - `{user_id}` — Your account ID (from **Account → Profile** in the console, or `vastai show user`). -- `sday` / `eday` — UTC day indices (days since 1970-01-01). Prefer `?last_days=N` on the API if you do not want to compute indices manually. - Settlement is evaluated on UTC day boundaries. Rows typically update within a few hours after UTC midnight. -The backtester's `historical_sla` replays past settlement and is not a live billing feed. For day-level per-machine reconciliation, use **Host → Billing**; use `last_days=1` API polling only when you need automation. - ## Tips for competitive SLA offers -- **Set claim above target.** A claim of 99% with a target of 95% produces a much lower premium than matching them both at 95%. -- **Tighten confidence only when earned.** Use high confidence (`sla_sigma_x ≈ 0.2`) after you have a strong uptime track record on that machine. -- **Keep the machine online during active contracts.** SLA payouts and verification are separate systems, but both respond to downtime. -- **SLA applies to on-demand rentals only.** It does not apply to interruptible/bid instances or reserved/prepay rentals. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. When a client starts an on-demand rental on an SLA-enabled offer, SLA terms lock for that rental contract and do not change if you later edit the offer. -- **Use the [SLA backtester](/host/sla-backtester) (API-only)** to preview how different targets and confidence levels would have affected past earnings. +- **Claim a level you can sustain.** Clients who choose targets below your claim see lower SLA charges and still get meaningful coverage. +- **Tighten confidence only when earned.** Use a tighter spread (`sla_sigma_x ≈ 0.2`) after you have a strong reliability track record on that machine. +- **Keep the machine online during active contracts.** SLA credits and verification are separate systems, but both respond to downtime. +- **SLA applies to on-demand rentals only.** It does not apply to interruptible/bid instances or reserved/prepay rentals. When a client starts an on-demand rental on an SLA-enabled offer, SLA terms lock for that rental contract and do not change if you later edit the offer. +- **Use the [SLA backtester](/host/sla-backtester) (API-only)** to preview how different claims and confidence levels would have affected past earnings. ## Related documentation +- [SLA Coverage (clients)](/guides/instances/choosing/sla-coverage) — how renters find and evaluate SLA offers - [SLA Earnings Backtester](/host/sla-backtester) — preview SLA economics on historical earnings - [Hosting Overview](/host/hosting-overview) — offers, rental contracts, and listing basics - [Understanding Verification](/host/understanding-verification) — platform verification (separate from SLA, but related to trust) diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index adf465d0..07ea34e8 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. -SLA parameters (`--sla_r_target`, `--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). +SLA parameters (`--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). For SLA listing via REST, see [SLA Offers — API (for automation)](/host/sla-offers#api-for-automation). Volume and duration options (`-v`, `-z`, `-l`) are available in the CLI today. REST callers should confirm supported `create_asks/` body fields in the [List Machine API reference](/api-reference/machines/list-machine) before sending them — some CLI-only fields may not yet appear in the published OpenAPI schema. diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index ce4562ff..5258f72d 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. -SLA parameters (`sla_r_target`, `sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). +SLA parameters (`sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). Volume and duration listing parameters (`vol_size`, `vol_price`, `duration`, `price_min_bid`) require the CLI or REST API today — they are not in the SDK signature below. From 0284517b13e78d6c5d7d8fe1ca46e215cbe2ad6e Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 13:46:51 -0700 Subject: [PATCH 17/45] docs(sla): address doc-review consensus (cycle 1) Clarify SLA opt-in and on-demand scope for clients, align search/instances OpenAPI, and remove internal release notes from the publishable tree. Co-authored-by: Cursor --- api-reference/openapi.yaml | 88 ++++++++++--- api-reference/openapi/yaml/search_offers.yaml | 24 +++- .../openapi/yaml/show_instances.yaml | 33 ++++- cli/reference/search-offers.mdx | 2 +- .../HOST-2752-SLA-API-Documentation.md | 37 ------ guides/instances/choosing/find-and-rent.mdx | 6 +- guides/instances/choosing/sla-coverage.mdx | 118 ++++++++++++------ host/hosting-overview.mdx | 6 +- host/sla-offers.mdx | 23 +++- snippets/host/cli/list-machine.mdx | 4 +- 10 files changed, 234 insertions(+), 107 deletions(-) delete mode 100644 docs/release-notes/HOST-2752-SLA-API-Documentation.md diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 6fc62732..54e3bed5 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -6616,8 +6616,31 @@ paths: - RTX_4090 reliability: type: object - description: 'Machine reliability score (0-1). Example: {"gte": - 0.99}' + description: 'Historical machine reliability score (0-1), not the + host SLA claim. Example: {"gte": 0.99}' + target_reliability: + type: object + description: 'Client SLA coverage target (0-1). When set, search + prices include the SLA charge in dph_total + + and returns search.slaPremiumPerHour. Example: {"eq": 0.95} + + ' + has_sla: + type: object + description: 'Restrict to offers with SLA enabled (true) or without + (false). Example: {"eq": true} + + ' + properties: + eq: + type: boolean + expected_reliability: + type: object + description: 'Host SLA claim on the offer (0-1). Example: {"gte": + 0.99} + + ' num_gpus: type: object description: 'Number of GPUs. Example: {"gte": 4} or {"in": [1, @@ -6916,7 +6939,13 @@ paths: vram_costperhour: 0.009876 webpage: null vms_enabled: false - expected_reliability: 0.5 + expected_reliability: 0.99 + search: + gpuCostPerHour: 0.123456 + diskHour: 0.123456 + totalHour: 0.234567 + discountTotalHour: 0.01 + discountedTotalPerHour: 0.224567 is_vm_deverified: false resource_type: gpu cluster_id: null @@ -6932,12 +6961,6 @@ paths: discount_rate: 0.05 discounted_hourly: 0.01 discounted_dph_total: 0.224567 - search: - gpuCostPerHour: 0.123456 - diskHour: 0.123456 - totalHour: 0.234567 - discountTotalHour: 0.01 - discountedTotalPerHour: 0.224567 instance: gpuCostPerHour: 0.01 diskHour: 0.02 @@ -8040,8 +8063,14 @@ paths: `gt`, `gte`, `lt`, `lte`, `in`, `notin`. Filterable columns: `actual_status`, `gpu_name`, `verification`, `id`, `label`, - and other columns stored directly on the contract record. Computed fields - (e.g. `dph_total`, `num_gpus`) are not filterable and return 400. + and other columns stored directly on the contract record + + (including `sla_r_claim` and `sla_r_target` / `target_reliability` when + present). Computed fields (e.g. `dph_total`, `num_gpus`, `has_sla`) are + not filterable and return 400. + + To find SLA-covered instances, filter client-side on `target_reliability + > 0` or use `select_filters` on `sla_r_target` if supported for your key. ' schema: @@ -8349,7 +8378,36 @@ paths: dph_total: type: number format: float + description: Total $/hour including storage (and SLA charge + when applicable). example: 0.8021 + target_reliability: + type: number + format: float + nullable: true + description: Client SLA coverage target locked at rent time. + Null or 0 when the rental has no SLA. + example: 0.95 + sla_r_claim: + type: number + format: float + nullable: true + description: Host reliability claim for this SLA contract. + example: 0.99 + sla_sigma_x: + type: number + format: float + nullable: true + description: Host confidence spread for this SLA contract. + example: 0.5 + search: + type: object + example: + gpuCostPerHour: 0.8 + diskHour: 0.0021 + totalHour: 0.8021 + discountTotalHour: 0 + discountedTotalPerHour: 0.8013 dlperf: type: - number @@ -8401,14 +8459,6 @@ paths: - string - 'null' example: null - search: - type: object - example: - gpuCostPerHour: 0.8 - diskHour: 0.0021 - totalHour: 0.8021 - discountTotalHour: 0 - discountedTotalPerHour: 0.8013 instance: type: object example: diff --git a/api-reference/openapi/yaml/search_offers.yaml b/api-reference/openapi/yaml/search_offers.yaml index fbf7ecdb..93a834dc 100644 --- a/api-reference/openapi/yaml/search_offers.yaml +++ b/api-reference/openapi/yaml/search_offers.yaml @@ -88,7 +88,23 @@ paths: example: ["RTX_3090", "RTX_4090"] reliability: type: object - description: 'Machine reliability score (0-1). Example: {"gte": 0.99}' + description: 'Historical machine reliability score (0-1), not the host SLA claim. Example: {"gte": 0.99}' + target_reliability: + type: object + description: | + Client SLA coverage target (0-1). When set, search prices include the SLA charge in dph_total + and returns search.slaPremiumPerHour. Example: {"eq": 0.95} + has_sla: + type: object + description: | + Restrict to offers with SLA enabled (true) or without (false). Example: {"eq": true} + properties: + eq: + type: boolean + expected_reliability: + type: object + description: | + Host SLA claim on the offer (0-1). Example: {"gte": 0.99} num_gpus: type: object description: 'Number of GPUs. Example: {"gte": 4} or {"in": [1, 2, 4, 8]}' @@ -362,7 +378,11 @@ paths: vram_costperhour: 0.009876 webpage: null vms_enabled: false - expected_reliability: 0.5 + expected_reliability: 0.99 + search: + slaPremiumPerHour: 0.008 + gpuCostPerHour: 3.5 + totalHour: 3.508 is_vm_deverified: false resource_type: "gpu" cluster_id: null diff --git a/api-reference/openapi/yaml/show_instances.yaml b/api-reference/openapi/yaml/show_instances.yaml index fdc28df8..d280c1d1 100644 --- a/api-reference/openapi/yaml/show_instances.yaml +++ b/api-reference/openapi/yaml/show_instances.yaml @@ -54,7 +54,9 @@ paths: required: false description: | JSON object of column filters. Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notin`. - Filterable columns: `actual_status`, `gpu_name`, `verification`, `id`, `label`, and other columns stored directly on the contract record. Computed fields (e.g. `dph_total`, `num_gpus`) are not filterable and return 400. + Filterable columns: `actual_status`, `gpu_name`, `verification`, `id`, `label`, and other columns stored directly on the contract record + (including `sla_r_claim` and `sla_r_target` / `target_reliability` when present). Computed fields (e.g. `dph_total`, `num_gpus`, `has_sla`) are not filterable and return 400. + To find SLA-covered instances, filter client-side on `target_reliability > 0` or use `select_filters` on `sla_r_target` if supported for your key. schema: type: string default: '{}' @@ -332,7 +334,36 @@ paths: dph_total: type: number format: float + description: Total $/hour including storage (and SLA charge when applicable). example: 0.8021 + target_reliability: + type: number + format: float + nullable: true + description: Client SLA coverage target locked at rent time. Null or 0 when the rental has no SLA. + example: 0.95 + sla_r_claim: + type: number + format: float + nullable: true + description: Host reliability claim for this SLA contract. + example: 0.99 + sla_sigma_x: + type: number + format: float + nullable: true + description: Host confidence spread for this SLA contract. + example: 0.5 + search: + type: object + description: Price breakdown for search-context costs (may include slaPremiumPerHour). + additionalProperties: true + properties: + slaPremiumPerHour: + type: number + format: float + description: SLA charge rate in $/hour (API field name). + example: 0.008 dlperf: type: number nullable: true diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 4d24bacd..b31331b4 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -148,7 +148,7 @@ vastai search offers 'cpu_arch=arm64' | `pci_gen` | float | PCIE generation | | `pcie_bw` | float | PCIE bandwidth (CPU to GPU) | | `reliability` | float | machine reliability score (see FAQ for explanation) | -| `expected_reliability` | float | host SLA claim (`sla_r_claim`); `0` when SLA is off | +| `expected_reliability` | float | host’s advertised SLA reliability claim on the offer | | `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | | `target_reliability` | float | your desired SLA coverage level; drives SLA charge in `dph_total` | | `rentable` | bool | is the instance currently rentable | diff --git a/docs/release-notes/HOST-2752-SLA-API-Documentation.md b/docs/release-notes/HOST-2752-SLA-API-Documentation.md deleted file mode 100644 index 23ef8f96..00000000 --- a/docs/release-notes/HOST-2752-SLA-API-Documentation.md +++ /dev/null @@ -1,37 +0,0 @@ -# HOST-2752: Host & client SLA documentation - -**Branch:** `HOST-2752-SLA-API-Documentation` -**Base:** `origin/main` -**Scope:** User-facing SLA docs aligned to v5 ask/search model and compliance wording. - -## Summary - -Documents SLA for hosts and clients under the current design: hosts publish a **claim** and **confidence** (`sla_r_claim`, `sla_sigma_x`); clients choose **target** at search/rent (`target_reliability`). User-facing copy uses **SLA charge** (not premium) and avoids insurance/betting language. - -## Details - -### Guides - -| Page | Path | Audience | -| --- | --- | --- | -| SLA Offers | `/host/sla-offers` | Hosts — claim/confidence listing, economics, monitoring | -| SLA Earnings Backtester | `/host/sla-backtester` | Hosts — historical replay (`r` = claim=target in sim) | -| SLA Coverage | `/guides/instances/choosing/sla-coverage` | Clients — search filters, charges, credits | - -### Model corrections vs earlier drafts - -- `sla_r_target` is **not** host-settable on asks (ignored if sent). -- SLA activates on `sla_r_claim > 0`; disable with `sla_r_claim = 0`. -- Optional `sla_max_beta` documented for advanced hosts. -- Backtester `beta` is derived from `r` for non-admins. -- Billing note: intended compute billed; compensation via settlement credits. - -### OpenAPI / nav - -- `list_machine.yaml`, `show_machines.yaml`, `sla_backtest.yaml`, `show_earnings.yaml` updated; `openapi.yaml` regenerated. -- `docs.json` adds client SLA Coverage under Find & rent. -- Search CLI docs list `has_sla`, `expected_reliability`, `target_reliability`. - -## Compliance wording - -Forbidden in user docs: insurance, premium (prefer **SLA charge**), betting, gambling, bet. API field names such as `slaPremiumPerHour` are documented as the SLA charge rate without using “premium” as prose. diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index af0b89be..eba3f28b 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -54,9 +54,9 @@ All stats shown are the portion of the total machine rented. - Disk speed: The speed of the local storage on the machine in MB/s - Total available disk: The maximum amount of disk space available - DLPERF score: A custom deep learning performance score -- Price: The GPU rental price plus the hourly cost of the storage allocated. Hover over the price for a breakdown and for the price of bandwidth. +- Price: The GPU rental price plus the hourly cost of the storage allocated. Hover over the price for a breakdown and for the price of bandwidth. On SLA listings, the breakdown also shows an **SLA charge** line — see [SLA Coverage](/guides/instances/choosing/sla-coverage). - Max Duration: The maximum length of a rental contract on this machine -- Reliability Score: A measure of the machine's historical uptime and health. All machines start at 60%. +- Reliability Score: A measure of the machine's historical uptime and health. All machines start at 60%. This is **not** the host SLA claim. Rental Option: RENT Button ## Instance Disk Size @@ -71,7 +71,7 @@ When the instance is created, the disk size is set and cannot be modified. It is ## Instance Configuration -Vast.ai provides out Linux docker instances. One key step during setup is specifying what Linux docker image to load. You can also specify Docker run commands, an on-start script that executes bash commands on instance start and a launch mode to connect to the instance. +Vast.ai provides Linux Docker instances. One key step during setup is specifying what Linux docker image to load. You can also specify Docker run commands, an on-start script that executes bash commands on instance start and a launch mode to connect to the instance. The instance configuration menu is accessible in the upper left of the create instance interface. The current template is always displayed in the upper left. Click on the "Change Template" button to bring up the template config menu that allows selecting and editing templates. For a quick overview, see [Choosing a Template](/guides/instances/choosing/templates). For detailed template creation and Docker configuration, see the main [Templates documentation](/guides/templates/introduction) diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 886c5f1b..0b01823b 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -4,43 +4,49 @@ description: "Rent GPU instances with reliability guarantees. Learn how SLA char "canonical": "/guides/instances/choosing/sla-coverage" --- -Some Vast.ai offers include a **Service Level Agreement (SLA)** — a reliability guarantee bundled with your on-demand rental. You choose a reliability **target** when you search, pay a small hourly **SLA charge** on top of compute, and if measured reliability falls short of that target, you receive settlement credits. +Some Vast.ai offers include a **Service Level Agreement (SLA)** — a reliability guarantee you can add to an **on-demand** rental. You choose a reliability **target** when you search, pay a small hourly **SLA charge** on top of compute, and if measured reliability falls short of that target, you receive settlement credits. This page explains SLA from the renter side: how to find SLA offers, how pricing works, and when you get credited. + +**SLA is opt-in.** Coverage applies only when you set a reliability target in Search before you rent (console or `target_reliability` in API/CLI). Renting without a target means **no SLA charge and no SLA credits**, even on offers where the host has enabled SLA. + + + +SLA applies to **on-demand rentals only** — not interruptible/bid or reserved/prepay contracts. See [Instance Pricing](/guides/instances/pricing). + + You do not post escrow or collateral for SLA. You pay the SLA charge while the instance runs. Settlement happens automatically on a daily cadence. ## What SLA protects -SLA is a **contractual, per-rental** reliability guarantee with automatic daily settlement. It is **not** the same as [verification](/host/understanding-verification) or the **reliability score** shown on offer cards — those are platform trust signals. +SLA is a **contractual, per-rental** reliability guarantee with automatic daily settlement. It is **not** the same as verification or the **reliability score** on offer cards — those are platform trust signals (see [Machine Tiers](/guides/instances/choosing/find-and-rent#machine-tiers)). For SLA-covered on-demand contracts: -- Compute is billed for the **intended** rental day (offline time is tracked as an outage in reliability measurements). -- **Settlement credits** compensate you when measured reliability falls short of your chosen target. -- On strong-reliability days, you simply pay the SLA charge with no credit. +- You are charged for **compute and the SLA charge** for the rental day, including periods when the instance is unavailable. +- Offline time is tracked as an outage in reliability measurements. +- If you qualify for compensation, a **settlement credit** posts after daily settlement (UTC) — typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. SLA is most useful for **long-running production workloads** where unexpected downtime has a real cost beyond the hourly rate. ## How pricing works -Total hourly cost with SLA: +Total hourly cost with SLA (`dph_total` = all-in dollars per hour in search): ``` total ≈ GPU + storage + bandwidth + SLA charge ``` -The SLA charge depends on: - -| Factor | Where it comes from | Effect | -| --- | --- | --- | -| Your reliability target | Your search filter (`target_reliability`) | Higher target → higher SLA charge | -| Host reliability claim | `expected_reliability` on the offer | Higher claim → lower SLA charge (at a given target) | -| Host confidence | Derived from `sla_sigma_x` on the offer | Tighter confidence → lower SLA charge | +| Factor | What it means for you | +| --- | --- | +| Your reliability target | Higher target → higher SLA charge | +| Host SLA claim | Maximum reliability the host advertises on the listing (`expected_reliability`). Higher claim → lower SLA charge at a given target | +| Host confidence | Host pricing setting that affects SLA charge size (tighter = lower charge at a given target) | -**Rule of thumb:** pick a target **at or below** the host's claim for the best value. If you ask for 99% coverage on a host who only claims 95%, the SLA charge is much higher than asking for 95% on a host who claims 99%. +**Rule of thumb:** pick a target **at or below** the host's claim for the best value. Asking for 99% coverage on a host who only claims 95% costs much more than asking for 95% on a host who claims 99%. ### Example: H100 at $3.50/hr GPU @@ -50,15 +56,20 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 | --- | --- | | GPU compute | $3.50/hr | | SLA charge | ~$0.008/hr | -| **Total** | ~$3.51/hr | - -The SLA charge is a small fraction of compute when the host's claim comfortably exceeds your target. +| **Total (`dph_total`)** | ~$3.51/hr | ## Finding SLA offers -### Search filters +### In the web console + +1. Open [Search](https://cloud.vast.ai/create/). +2. Set your **reliability target** in Search filters (and optionally filter to SLA-enabled offers). Exact control labels match the UI. +3. Confirm the price breakdown shows an **SLA charge** line and that **total $/hr** includes it before you rent. +4. The target you set here is what locks in at rent time. -Use these filters in [Search](https://cloud.vast.ai/create/) or the [search offers API](/api-reference/search/search-offers): +CLI and API examples below use the same filters. + +### Search filters | Filter | Meaning | Example | | --- | --- | --- | @@ -66,6 +77,10 @@ Use these filters in [Search](https://cloud.vast.ai/create/) or the [search offe | `has_sla` | Restrict to offers with (or without) SLA enabled. | `has_sla=true` | | `expected_reliability` | Filter by the host's advertised claim. | `expected_reliability>=0.99` | + +**API integrators:** `reliability` is the historical machine score, not the host’s SLA claim. Use `has_sla=true` and/or `expected_reliability` to find SLA listings. + + **CLI examples:** ```bash @@ -80,37 +95,45 @@ When you set `target_reliability`, search results include: | Response field | Meaning | | --- | --- | -| `search.slaPremiumPerHour` | SLA charge for this offer at your target (API field name; this is the SLA charge rate) | +| `search.slaPremiumPerHour` | SLA charge for this offer at your target (API field name) | | `dph_total` | Total hourly cost **including** the SLA charge | | `expected_reliability` | Host's reliability claim | -Hover the price breakdown on an offer card to see GPU, storage, bandwidth, and the SLA charge separately. +Hover over the price breakdown on an offer card to see GPU, storage, bandwidth, and the SLA charge separately. -When you search with an SLA target, **reserved-instance discounts are not applied** to the displayed total. SLA charges are never discounted. +When you search with an SLA target, reserved-instance discounts may not apply to the displayed total. Confirm in the console price breakdown. SLA charges are never discounted. ### Comparing offers -Two offers at the same GPU price can have very different SLA costs: - | Offer | GPU/hr | Host claim | Your target | SLA charge/hr | | --- | --- | --- | --- | --- | | A | $3.50 | 99% | 95% | ~$0.008 | | B | $3.50 | 95% | 95% | much higher | -Offer A is dramatically cheaper on SLA because the host claims more headroom above your target. Always compare **`dph_total`**, not just GPU price, when SLA matters. +Always compare **`dph_total`**, not just GPU price, when SLA matters. Search ranking also accounts for SLA cost. + +### API automation -Search ranking also accounts for SLA cost — offers with expensive coverage at your target rank lower per dollar of performance. +1. **Search** with `target_reliability` set (and optionally `has_sla=true`, `expected_reliability>=…`) in the same request you use to pick an offer. +2. **Rent** the offer ID from that search response so pricing and contract terms match `dph_total`. +3. **Verify** on the new instance: `target_reliability` and related SLA fields in show-instances output. + +`target_reliability` is a **search-time** parameter; create-instance does not accept separate SLA fields — terms come from the search context used before rent. ## What happens after you rent -When you rent an SLA-backed offer: +When you rent an SLA-backed offer **with a target set**: -1. **Contract terms lock in** — your reliability target, the host's claim, and confidence spread are fixed for that rental. +1. **Contract terms lock in** — your reliability target, the host's claim, and confidence are fixed for that rental. 2. **Daily billing** — you pay compute plus the SLA charge each day. 3. **Daily settlement** — Vast measures reliability across multiple timescales and calculates any SLA credit. -4. **Credits appear in billing** — positive credits improve your balance; strong days mean you paid the SLA charge with no credit. +4. **Credits appear in billing** — settlement credits improve your balance; strong days mean you paid the SLA charge with no credit. + +### What you pay during an outage + +You are still charged for **compute and the SLA charge** for the rental day while the instance is unavailable. If you qualify for compensation, a **settlement credit** is applied after daily settlement (UTC), typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. ### How reliability is measured @@ -126,13 +149,15 @@ Scheduled maintenance with adequate notice may be credited toward reliability. U Using the H100 example ($84/day compute, ~$0.20/day SLA charge, target 95%, host claim 99%): -| Day's measured reliability (simplified) | What you pay | What you receive | Your net vs no-SLA baseline | +| Day's measured reliability (simplified) | What you pay | What you receive | Extra cost vs no SLA | | --- | --- | --- | --- | -| Excellent (~100%) | $84 compute + $0.20 SLA charge | — | −$0.20 | -| Good (~99%) | $84 + $0.20 | Small credit | Roughly −$0.17 | +| Excellent (~100%) | $84 compute + $0.20 SLA charge | — | −$0.20 (you paid the SLA charge) | +| Good (~99%) | $84 + $0.20 | Often none / small credit | Roughly −$0.20 to −$0.17 | | At target (~95%) | $84 + $0.20 | ~$42 credit | ~+$42 | | Severe outage (~90% or less) | $84 + $0.20 | ~$84 credit | ~+$84 | +Negative values in the last column mean you paid a small SLA charge on top of compute; positive values mean you received a settlement credit. Strong-uptime days often yield no credit in production settlement. + Production settlement uses the multi-window reliability blend described above, not a single raw daily percentage. Treat these rows as directional, not exact invoice amounts. @@ -143,11 +168,18 @@ Production settlement uses the multi-window reliability blend described above, n - Credits accumulate on your instance charges and transfer to your account balance. - When your contract ends, any remaining unsettled days are resolved at close. +## If your instance goes down + +1. Save work and check **Instances** for host/maintenance status. +2. Remember: compute and SLA charges continue until settlement; credits apply to the **previous UTC day**, not the current hour. +3. After settlement, check **Account → Billing** (Charges / billing history) for SLA line items. +4. If credits still look wrong **48 hours** after the outage day, contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or [contact@vast.ai](mailto:contact@vast.ai). + ## Viewing SLA on active instances On the [Instances](https://cloud.vast.ai/instances/) page, price details for SLA rentals include the SLA charge rate alongside GPU and storage costs. -The [show instances API](/api-reference/instances/show-instances) exposes SLA fields on each contract: +Show-instances output may include: | Field | Meaning | | --- | --- | @@ -156,10 +188,24 @@ The [show instances API](/api-reference/instances/show-instances) exposes SLA fi | `sla_sigma_x` | Host's confidence spread | | `search.slaPremiumPerHour` | Current SLA charge rate (API field name) | -Filter active instances with `has_sla=true` in the query. +To find SLA-covered instances, inspect returned objects for `target_reliability > 0` (or filter in your client). The show-instances API does **not** support a `has_sla` query parameter. + +
+API integrators — field aliases + +| Console / concept | API / raw field | +| --- | --- | +| Host SLA claim | `expected_reliability` on offers; `sla_r_claim` on contracts | +| Host confidence | `sla_sigma_x` | +| SLA charge rate | `search.slaPremiumPerHour` / `instance.slaPremiumPerHour` | +| Your target | `target_reliability` | + +These fields appear in CLI `--raw` output when SLA is active. Confirm against a live `--raw` response before building parsers. +
## When SLA is not available +- **Interruptible (bid) rentals** never include SLA, even on SLA-enabled machines. Use on-demand with a reliability target set. - **Prepaid / reserved-only flows** may reject SLA parameters. Use on-demand rentals for SLA coverage. - Offers without SLA (`expected_reliability = 0` / `has_sla=false`) are excluded when you filter with `has_sla=true` or set a positive `target_reliability`. - If SLA parameters on an offer are invalid for your target, search may flag an SLA pricing error instead of showing a charge. @@ -176,11 +222,11 @@ No. The target is fixed when the contract is created. End the instance and rent ### Does SLA replace verification? -No. Verification is a platform quality signal. SLA is a financial guarantee on a specific contract. A verified machine can still have SLA; an unverified machine may also offer SLA. +No. Verification is a platform quality signal (see [Machine Tiers](/guides/instances/choosing/find-and-rent#machine-tiers)). SLA is a financial guarantee on a specific contract. ### Where do I see historical SLA credits? -Check your billing history and instance charges. SLA line items appear alongside compute charges for each settled day. +Check **Account → Billing** and instance charges. SLA line items appear alongside compute charges for each settled day. ## Related documentation diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 5457b68e..78aebd3c 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -303,7 +303,7 @@ No, there is not an established process for hosts to message clients on Vast. ### I fear I will decrease my reliability from restarting my machine and potentially lose my verification. -Your machine's reliability does not directly affect your verification standing. Verification is independent of reliability. Though, whenever taking your machine offline and working on it you should proceed with caution as it is easy to introduce new issues or errors that will cause your machine to be de-verified. +Your machine's reliability does not directly affect your verification standing. Verification is independent of reliability. However, when you take your machine offline to work on it, proceed with caution—especially if you have active rental contracts. ### How much can I make hosting on Vast? @@ -315,7 +315,9 @@ If the machine loses connection, or if a client instance fails to start, the mac ### How do I minimize my reliability dropping? -Do not take your machine offline. If you must take your machine offline, minimize the time you have it offline. Note: reliability takes into account the average earnings of the machine, and machines with less earnings get penalized less from offline time. +Do not take your machine offline. If you must take your machine offline, minimize the time you have it offline. + +This advice applies to your marketplace **reliability score**, not SLA settlement. The dashboard score reflects connection and start reliability over recent activity. SLA uses separate measurement and daily credits — see [Machine reliability score vs SLA reliability](/host/sla-offers#machine-reliability-score-vs-sla-reliability). ### If someone has already used an image on my machine does redownload happen or is the system smart? diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index eb18540a..dd9554a9 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -27,11 +27,19 @@ SLA settlement is **asymmetric by design**: when reliability is strong relative ## Before you enable SLA +**Pre-flight checklist (before tuning claim/confidence):** + +- Confirm SLA is enabled for your account (contact [Discord](https://discord.gg/hSuEbSQ4X8) / support if unsure). +- Ensure your host daemon is current per the [host setup guide](https://cloud.vast.ai/host/setup/). +- If listing fails with `sla_not_approved` or `sla_daemon_outdated`, resolve eligibility before changing SLA parameters. + Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machine appears on **Host → Machines** with no red error status. Before enabling SLA, finish normal listing setup: test your machine, set GPU price and offer end date, choose on-demand vs interruptible, and understand [Testing your own machine](/host/hosting-overview#testing-your-own-machine) and offer terms in [Hosting overview](/host/hosting-overview). -SLA listing may require host approval and a sufficiently recent daemon. If listing fails with `sla_not_approved` or `sla_daemon_outdated`, contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or update the daemon from the host setup page. + +On outage days you may still bill clients for **intended** compute **and** owe SLA settlement credits. Tail-risk exposure can approach a full day’s compute per affected contract — not just the daily SLA charge shown in previews. Read [Billing vs settlement](#billing-vs-settlement-important) before enabling SLA. + **Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. Interruptible instances on an SLA-enabled machine are not SLA-covered; on-demand contracts on the same machine are. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. @@ -89,7 +97,10 @@ When you list or update a machine, set SLA fields via the host console or `PUT / | --- | --- | --- | --- | | Reliability claim | `sla_r_claim` | `r` (backtester sets claim = target = `r`) | Your advertised belief about machine reliability. Set above `0` to enable SLA. Values are greater than 0 and at most **0.9999** (for example, `0.99` = 99%). Exactly `1.0` is rejected. Set to `0` to disable SLA on new rentals. | | Confidence spread | `sla_sigma_x` | `p` (different scale — see [backtester](/host/sla-backtester#confidence-values-p)) | How wide your belief is around the claim. Lower = more confident (lower SLA charges for clients at a given target). Defaults to `0.5` if omitted. | -| Max client β (optional) | `sla_max_beta` | — | Advanced term capping how path-dependent a client's timescale mix can be. Most hosts can omit this. Must be in `(0, 1)` and at least the default β derived at your claim. | + +### Advanced: `sla_max_beta` (optional) + +Omit unless Vast support directs you. Optional ask term `sla_max_beta` limits how path-dependent a client's timescale mix can be for long-running contracts. Must be in `(0, 1)` and at least the default β derived at your claim. Most hosts should leave it unset. **`sla_r_target` is not host-settable.** If you send `sla_r_target` or legacy `sla_reliability` on `create_asks/`, they are **ignored**. Clients supply their coverage target at search/rent time (`target_reliability`). Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x` — they use different scales. Use the mapping table on the [backtester page](/host/sla-backtester#confidence-values-p). @@ -108,7 +119,7 @@ When you list or update a machine, set SLA fields via the host console or `PUT / ### Machine reliability score vs SLA reliability -The **reliability score** on the Host Machines page reflects connection and instance-start behavior (and is earnings-weighted). **SLA settlement** measures whether covered instances met the client's published uptime target for billing purposes. +The **reliability score** on the Host Machines page reflects connection and instance-start behavior over recent activity. **SLA settlement** measures whether covered instances met the client's published uptime target for billing purposes. Do not assume the dashboard score equals SLA reliability. Before choosing `sla_r_claim`: @@ -171,7 +182,9 @@ If the machine is already **listed**: 1. Open **Host → Machines → Set Pricing → SLA**, set Claim and Confidence, then click **Save**. 2. **Save** applies SLA to the live offer — you do not need to click **LIST** again unless this is a brand-new listing that was never published. -3. Verify in search: `dph_total` includes the SLA charge at a client's `target_reliability`, and `expected_reliability` matches your claim (see [Search / client-visible fields](#search--client-visible-fields)). +3. Verify after listing: + - **Console:** confirm the machine status is **Listed**, reopen **Set Pricing → SLA** to review the preview, or check offer details under **Host → Machines**. + - **Search:** `dph_total` includes the SLA charge at a client's `target_reliability`, and `expected_reliability` matches your claim (see [Search / client-visible fields](#search--client-visible-fields)). In the web console, **Set Pricing → Save** stores SLA settings; clicking **LIST** publishes the offer to search. `PUT /api/v0/machines/create_asks/` performs both steps in one request — it creates or updates the **live listing** (same as pressing **LIST** or running `vastai list machine`), not a save-only draft. @@ -413,6 +426,8 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) may be credited back toward reliability, reducing SLA penalties for planned downtime. Unplanned outages count fully toward SLA settlement. +**Console-only hosts:** SLA credit for planned downtime requires scheduling maintenance at least 24 hours ahead. Today this is done via the CLI (`vastai schedule maint`). Install the CLI before enabling SLA if you rely on planned maintenance credits. + Planned maintenance credit is not guaranteed. The platform evaluates advance notice (generally at least 24 hours recommended) and maintenance duration when determining credit eligibility. **Treat any scheduled downtime as a potential SLA credit event when modeling risk.** Contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or email [contact@vast.ai](mailto:contact@vast.ai) before extended maintenance on an SLA-listed machine to confirm credit eligibility. diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 07ea34e8..d935e4ad 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -3,9 +3,9 @@ Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. -SLA parameters (`--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). +SLA parameters (`--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation) and [List Machine](/api-reference/machines/list-machine). -For SLA listing via REST, see [SLA Offers — API (for automation)](/host/sla-offers#api-for-automation). Volume and duration options (`-v`, `-z`, `-l`) are available in the CLI today. REST callers should confirm supported `create_asks/` body fields in the [List Machine API reference](/api-reference/machines/list-machine) before sending them — some CLI-only fields may not yet appear in the published OpenAPI schema. +Volume and duration options (`-v`, `-z`, `-l`) are available in the CLI today. ## Usage From d449516af24d5ada4a781ad2130cb334a19f3dd5 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 13:53:32 -0700 Subject: [PATCH 18/45] docs(sla): address doc-review consensus (cycle 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document search→rent SLA binding with REST examples, clarify console opt-in and maintenance CLI paths, and fix OpenAPI slaPremiumPerHour examples. Co-authored-by: Cursor --- api-reference/openapi.yaml | 51 ++++++++++---- api-reference/openapi/yaml/search_offers.yaml | 6 +- .../openapi/yaml/show_instances.yaml | 28 +++++--- cli/reference/search-offers.mdx | 3 +- guides/instances/choosing/find-and-rent.mdx | 7 +- guides/instances/choosing/sla-coverage.mdx | 67 ++++++++++++------- host/hosting-overview.mdx | 10 ++- host/sla-offers.mdx | 15 ++++- snippets/host/cli/schedule-maint.mdx | 4 +- 9 files changed, 130 insertions(+), 61 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 54e3bed5..eba64977 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -6940,12 +6940,6 @@ paths: webpage: null vms_enabled: false expected_reliability: 0.99 - search: - gpuCostPerHour: 0.123456 - diskHour: 0.123456 - totalHour: 0.234567 - discountTotalHour: 0.01 - discountedTotalPerHour: 0.224567 is_vm_deverified: false resource_type: gpu cluster_id: null @@ -6961,9 +6955,17 @@ paths: discount_rate: 0.05 discounted_hourly: 0.01 discounted_dph_total: 0.224567 + search: + gpuCostPerHour: 0.123456 + diskHour: 0.123456 + slaPremiumPerHour: 0.008 + totalHour: 0.234567 + discountTotalHour: 0.01 + discountedTotalPerHour: 0.224567 instance: gpuCostPerHour: 0.01 diskHour: 0.02 + slaPremiumPerHour: 0.008 totalHour: 0.03 discountTotalHour: 0.001 discountedTotalPerHour: 0.029 @@ -8400,14 +8402,6 @@ paths: nullable: true description: Host confidence spread for this SLA contract. example: 0.5 - search: - type: object - example: - gpuCostPerHour: 0.8 - diskHour: 0.0021 - totalHour: 0.8021 - discountTotalHour: 0 - discountedTotalPerHour: 0.8013 dlperf: type: - number @@ -8459,11 +8453,40 @@ paths: - string - 'null' example: null + search: + type: object + description: Price breakdown for search-context costs (may + include slaPremiumPerHour). + additionalProperties: true + properties: + slaPremiumPerHour: + type: number + format: float + description: SLA charge rate in $/hour (API field name). + example: 0.008 + example: + gpuCostPerHour: 0.8 + diskHour: 0.0021 + slaPremiumPerHour: 0.008 + totalHour: 0.8021 + discountTotalHour: 0 + discountedTotalPerHour: 0.8013 instance: type: object + description: Price breakdown for instance-context costs + (may include slaPremiumPerHour while running). + additionalProperties: true + properties: + slaPremiumPerHour: + type: number + format: float + description: SLA charge rate in $/hour while the instance + is running (API field name). + example: 0.008 example: gpuCostPerHour: 0.8 diskHour: 0.0013 + slaPremiumPerHour: 0.008 totalHour: 0.8021 discountTotalHour: 0 discountedTotalPerHour: 0.5034 diff --git a/api-reference/openapi/yaml/search_offers.yaml b/api-reference/openapi/yaml/search_offers.yaml index 93a834dc..16ab5bbe 100644 --- a/api-reference/openapi/yaml/search_offers.yaml +++ b/api-reference/openapi/yaml/search_offers.yaml @@ -379,10 +379,6 @@ paths: webpage: null vms_enabled: false expected_reliability: 0.99 - search: - slaPremiumPerHour: 0.008 - gpuCostPerHour: 3.5 - totalHour: 3.508 is_vm_deverified: false resource_type: "gpu" cluster_id: null @@ -401,12 +397,14 @@ paths: search: gpuCostPerHour: 0.123456 diskHour: 0.123456 + slaPremiumPerHour: 0.008 totalHour: 0.234567 discountTotalHour: 0.01 discountedTotalPerHour: 0.224567 instance: gpuCostPerHour: 0.01 diskHour: 0.02 + slaPremiumPerHour: 0.008 totalHour: 0.03 discountTotalHour: 0.001 discountedTotalPerHour: 0.029 diff --git a/api-reference/openapi/yaml/show_instances.yaml b/api-reference/openapi/yaml/show_instances.yaml index d280c1d1..88f4bf83 100644 --- a/api-reference/openapi/yaml/show_instances.yaml +++ b/api-reference/openapi/yaml/show_instances.yaml @@ -354,16 +354,6 @@ paths: nullable: true description: Host confidence spread for this SLA contract. example: 0.5 - search: - type: object - description: Price breakdown for search-context costs (may include slaPremiumPerHour). - additionalProperties: true - properties: - slaPremiumPerHour: - type: number - format: float - description: SLA charge rate in $/hour (API field name). - example: 0.008 dlperf: type: number nullable: true @@ -412,17 +402,35 @@ paths: example: null search: type: object + description: Price breakdown for search-context costs (may include slaPremiumPerHour). + additionalProperties: true + properties: + slaPremiumPerHour: + type: number + format: float + description: SLA charge rate in $/hour (API field name). + example: 0.008 example: gpuCostPerHour: 0.8 diskHour: 0.0021 + slaPremiumPerHour: 0.008 totalHour: 0.8021 discountTotalHour: 0 discountedTotalPerHour: 0.8013 instance: type: object + description: Price breakdown for instance-context costs (may include slaPremiumPerHour while running). + additionalProperties: true + properties: + slaPremiumPerHour: + type: number + format: float + description: SLA charge rate in $/hour while the instance is running (API field name). + example: 0.008 example: gpuCostPerHour: 0.8 diskHour: 0.0013 + slaPremiumPerHour: 0.008 totalHour: 0.8021 discountTotalHour: 0 discountedTotalPerHour: 0.5034 diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index b31331b4..731e0a02 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -147,10 +147,11 @@ vastai search offers 'cpu_arch=arm64' | `num_gpus` | int | number of GPUs | | `pci_gen` | float | PCIE generation | | `pcie_bw` | float | PCIE bandwidth (CPU to GPU) | +| `dph_total` | float | total $/hr in search results (compute + storage + SLA charge when applicable) | | `reliability` | float | machine reliability score (see FAQ for explanation) | | `expected_reliability` | float | host’s advertised SLA reliability claim on the offer | | `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | -| `target_reliability` | float | your desired SLA coverage level; drives SLA charge in `dph_total` | +| `target_reliability` | float | your desired SLA coverage level; drives SLA charge in `dph_total` (see [SLA Coverage](/guides/instances/choosing/sla-coverage)) | | `rentable` | bool | is the instance currently rentable | | `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances | | `storage_cost` | float | storage cost in $/GB/month | diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index eba3f28b..edd5f264 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -21,7 +21,7 @@ You will find various search options on the top and left control bars that allow The offer card shows the details of a machine available for rent, including specs, pricing, and the maximum rental duration. When you rent an instance, a rental contract is created between you and the host based on the offer's current terms. The offer remains available for other clients until it reaches its end date or is unlisted by the host. -Most of the items on the offer card can be filtered using the search filters. Some of the important parts are the price and the maximum rental duration. Hovering over the price details the different prices for GPU rental, storage and bandwidth. +Most of the items on the offer card can be filtered using the search filters. Some of the important parts are the price and the maximum rental duration. Hovering over the price shows the different prices for GPU rental, storage, and bandwidth. ### Machine Tiers @@ -46,7 +46,7 @@ All stats shown are the portion of the total machine rented. - Motherboard: The name of the motherboard manufacturer and type - Motherboard details: PCIE version and number of lanes along with maximum theoretical PCIE bandwidth in GB/s - CPU: The CPU type -- CPU Cores: the number of cores allocated for this offer divided total +- CPU Cores: the number of cores allocated for this offer divided by the total - System RAM: system RAM allocated for this offer divided by the total - Network Bandwidth: Given in Mbps for upload/download - Network Ports: number of potential ports available @@ -57,7 +57,8 @@ All stats shown are the portion of the total machine rented. - Price: The GPU rental price plus the hourly cost of the storage allocated. Hover over the price for a breakdown and for the price of bandwidth. On SLA listings, the breakdown also shows an **SLA charge** line — see [SLA Coverage](/guides/instances/choosing/sla-coverage). - Max Duration: The maximum length of a rental contract on this machine - Reliability Score: A measure of the machine's historical uptime and health. All machines start at 60%. This is **not** the host SLA claim. - Rental Option: RENT Button +- Rental Option: RENT button +- **SLA (optional):** Available on **on-demand** rentals only. Set a **reliability target** in Search before clicking **RENT** to opt in — see [SLA Coverage](/guides/instances/choosing/sla-coverage). ## Instance Disk Size diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 0b01823b..0a4d0677 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -62,10 +62,10 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 ### In the web console -1. Open [Search](https://cloud.vast.ai/create/). -2. Set your **reliability target** in Search filters (and optionally filter to SLA-enabled offers). Exact control labels match the UI. -3. Confirm the price breakdown shows an **SLA charge** line and that **total $/hr** includes it before you rent. -4. The target you set here is what locks in at rent time. +1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). +2. In the search filters panel, set your **reliability target** (exact label matches the current UI—typically under advanced or SLA filters). +3. Review offers that show an **SLA charge** line in the price breakdown. If you do not see an SLA charge before clicking **RENT**, you do not have coverage. +4. Rent as usual. Your target is locked at rent time. CLI and API examples below use the same filters. @@ -116,11 +116,32 @@ Always compare **`dph_total`**, not just GPU price, when SLA matters. Search ran ### API automation -1. **Search** with `target_reliability` set (and optionally `has_sla=true`, `expected_reliability>=…`) in the same request you use to pick an offer. -2. **Rent** the offer ID from that search response so pricing and contract terms match `dph_total`. -3. **Verify** on the new instance: `target_reliability` and related SLA fields in show-instances output. + +Searching without `target_reliability`, then calling create-instance on that offer ID, does **not** add SLA retroactively. SLA terms are locked only when `target_reliability` is set in the **same** search request used to select the offer. + -`target_reliability` is a **search-time** parameter; create-instance does not accept separate SLA fields — terms come from the search context used before rent. +**REST search example** (filter shape differs from CLI query strings — see [Search Offers](/api-reference/search/search-offers)): + +```bash +curl -s -X POST "https://console.vast.ai/api/v0/bundles/" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "limit": 20, + "type": "ondemand", + "target_reliability": {"eq": 0.95}, + "has_sla": {"eq": true}, + "expected_reliability": {"gte": 0.99} + }' +``` + +1. **Search** with your target as above (and optionally `has_sla` / `expected_reliability`). +2. **Rent** the chosen offer with `PUT /api/v0/asks/{id}/` ([Create Instance](/api-reference/instances/create-instance)) — no SLA fields on create-instance. +3. **Verify** via show-instances: confirm `target_reliability > 0` and note `search.slaPremiumPerHour`. + +If your automation splits search and rent across workers, pass the search parameters (or offer ID plus confirmed `dph_total` and `target_reliability`) explicitly between steps — do not assume account-wide defaults apply SLA. + +Hold `--storage` / allocated storage constant when comparing `dph_total` across runs. ## What happens after you rent @@ -149,14 +170,15 @@ Scheduled maintenance with adequate notice may be credited toward reliability. U Using the H100 example ($84/day compute, ~$0.20/day SLA charge, target 95%, host claim 99%): -| Day's measured reliability (simplified) | What you pay | What you receive | Extra cost vs no SLA | +| Scenario | Approx. SLA charge | Approx. settlement credit | Net vs no SLA (approx.) | | --- | --- | --- | --- | -| Excellent (~100%) | $84 compute + $0.20 SLA charge | — | −$0.20 (you paid the SLA charge) | -| Good (~99%) | $84 + $0.20 | Often none / small credit | Roughly −$0.20 to −$0.17 | -| At target (~95%) | $84 + $0.20 | ~$42 credit | ~+$42 | -| Severe outage (~90% or less) | $84 + $0.20 | ~$84 credit | ~+$84 | +| Above target (excellent / good day) | ~$0.20/day | $0 (often) | **−$0.20** (you paid the SLA charge) | +| Near / below target on blended measure (~95%) | ~$0.20/day | ~$42 | **+$41.80** (net credit after SLA charge) | +| Severe shortfall (~90% or less) | ~$0.20/day | ~$84 | **+$83.80** | + +**How to read “Net vs no SLA”:** negative = you paid more than without SLA; positive = you received a net credit versus renting the same offer without SLA coverage. -Negative values in the last column mean you paid a small SLA charge on top of compute; positive values mean you received a settlement credit. Strong-uptime days often yield no credit in production settlement. +Production settlement can issue credits even when a single daily snapshot looks close to your target, because measurement uses the blended daily reliability calculation. Production settlement uses the multi-window reliability blend described above, not a single raw daily percentage. Treat these rows as directional, not exact invoice amounts. @@ -177,18 +199,17 @@ Production settlement uses the multi-window reliability blend described above, n ## Viewing SLA on active instances -On the [Instances](https://cloud.vast.ai/instances/) page, price details for SLA rentals include the SLA charge rate alongside GPU and storage costs. +### In the web console -Show-instances output may include: +1. Open **Instances** and select your running instance. +2. Open **price details** (or the instance billing panel) and confirm an **SLA charge** line is present. +3. If the UI shows your **reliability target**, confirm it matches what you selected at search time. If you do not see a target or SLA charge, you likely rented without SLA coverage. -| Field | Meaning | -| --- | --- | -| `target_reliability` | Your coverage target | -| `sla_r_claim` | Host's claim | -| `sla_sigma_x` | Host's confidence spread | -| `search.slaPremiumPerHour` | Current SLA charge rate (API field name) | +### API / CLI + +Show-instances output may include `target_reliability` and price fields under `search` / `instance` (including `slaPremiumPerHour`). -To find SLA-covered instances, inspect returned objects for `target_reliability > 0` (or filter in your client). The show-instances API does **not** support a `has_sla` query parameter. +To find SLA-covered instances, inspect returned objects for `target_reliability > 0` (or filter in your client). The show-instances API does **not** support a `has_sla` query parameter. Where your API key supports it, you may also try `select_filters` on `sla_r_target` / `target_reliability` — see [Show Instances](/api-reference/instances/show-instances).
API integrators — field aliases diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 78aebd3c..8caac1fd 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -235,7 +235,12 @@ The proper way to perform maintenance on your machine is to wait until all activ Unlisting the offer will prevent new rental contracts from being created, but does not affect existing ones. However if you have active rental contracts, you could set the offer end date to match the latest rental end date, allowing new clients to rent instances that end at the same date. Once the end date is reached, you can then unlist the machine and then perform maintenance. -Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored. You cannot take the machine offline until every active rental contract has ended. +Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored. + +You have two maintenance paths: + +1. **After contracts end:** Take the machine offline once every active rental contract has ended (default path). +2. **During active SLA contracts:** Use planned maintenance via [`vastai schedule maint`](/host/cli/schedule-maint) with at least 24 hours’ notice. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance) for credit rules. For unplanned or unscheduled maintenance, use the CLI and the [`vastai schedule maint`](/host/cli/schedule-maint) command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. @@ -267,8 +272,9 @@ You can create an invoice by going to the "Billing" page, and then click the box If your machine seems unlisted or missing from console search: +- Confirm **Listed** status on **Host → Machines**. - **CLI check:** `vastai search offers 'machine_id=MACHINE_ID verified=any'` — if this returns a result, your machine is listed. -- **Console search:** There are 10,000+ listings; search shows a small subset. You usually cannot find one specific machine through normal browsing — this is expected. +- Individual machines can be hard to find in broad console search; looking up by `machine_id` is the reliable check. - **Ranking check:** Use narrow filters to see similar machines, e.g. `vastai search offers 'gpu_name=RTX_4090 cpu_ram>257 cpu_ram<258'`. See also [Why is my machine not listed?](#why-is-my-machine-not-listed) below. diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index dd9554a9..a2607f09 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -29,9 +29,10 @@ SLA settlement is **asymmetric by design**: when reliability is strong relative **Pre-flight checklist (before tuning claim/confidence):** -- Confirm SLA is enabled for your account (contact [Discord](https://discord.gg/hSuEbSQ4X8) / support if unsure). +- Confirm SLA is enabled for your account. In the console, open **Set Pricing → SLA** on a machine — if the panel is missing or listing returns `sla_not_approved`, contact [Discord](https://discord.gg/hSuEbSQ4X8) before configuring a fleet. Test one machine before looping fleet scripts. - Ensure your host daemon is current per the [host setup guide](https://cloud.vast.ai/host/setup/). - If listing fails with `sla_not_approved` or `sla_daemon_outdated`, resolve eligibility before changing SLA parameters. +- **Planned maintenance:** SLA credit for scheduled downtime requires the [CLI](/cli/hello-world) (`vastai schedule maint`). If you rely on the web console only, install the CLI before enabling SLA, or accept that planned-maintenance credits may not be available until you do. Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machine appears on **Host → Machines** with no red error status. @@ -172,7 +173,7 @@ Disabling SLA on the offer (setting `sla_r_claim` to `0`) prevents new SLA-cover 1. Open your machine on the [Host Machines page](https://cloud.vast.ai/host/machines) → **Set Pricing**. 2. Set base listing fields first (GPU price, offer end date, rental types) if this is a new listing. 3. Expand **SLA**. -4. Set **Claim** and **Confidence** (spread). Example: claim **99%** with normal confidence. +4. Set **Claim** and **Confidence**. For your first listing, choose **Normal** (`sla_sigma_x ≈ 0.5`) unless your uptime history is volatile — see [Confidence values](#confidence-values) for risk tradeoffs. 5. Save and confirm the SLA charge preview before listing. 6. After saving pricing, click **LIST** on the Host Machines page (or confirm the machine status changes to **listed**). Saving pricing alone stores your offer settings; listing publishes the offer to search. @@ -426,7 +427,15 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) may be credited back toward reliability, reducing SLA penalties for planned downtime. Unplanned outages count fully toward SLA settlement. -**Console-only hosts:** SLA credit for planned downtime requires scheduling maintenance at least 24 hours ahead. Today this is done via the CLI (`vastai schedule maint`). Install the CLI before enabling SLA if you rely on planned maintenance credits. +Schedule at least 24 hours ahead when possible: + +```bash +vastai schedule maint MACHINE_ID --sdate "2026-08-01 02:00:00" --duration 2 +``` + +See [CLI install](/cli/hello-world) if you have not set up the CLI. Credits for planned maintenance are evaluated on a case-by-case basis and are not guaranteed. + +**Console-only hosts:** install the CLI before enabling SLA if you rely on planned maintenance credits. Planned maintenance credit is not guaranteed. The platform evaluates advance notice (generally at least 24 hours recommended) and maintenance duration when determining credit eligibility. **Treat any scheduled downtime as a potential SLA credit event when modeling risk.** Contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or email [contact@vast.ai](mailto:contact@vast.ai) before extended maintenance on an SLA-listed machine to confirm credit eligibility. diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 196ca1ba..4c15dee8 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -5,9 +5,11 @@ Schedule upcoming maint window ## Usage ```bash -vastai schedule maintenance id [--sdate START_DATE --duration DURATION --maintenance_category MAINTENANCE_CATEGORY] +vastai schedule maint id [--sdate START_DATE --duration DURATION --maintenance_category MAINTENANCE_CATEGORY] ``` +`schedule maintenance` is an alias for `schedule maint` if your CLI build supports both spellings. Prefer `maint`. + ## Arguments From 74a24a323497532ae3ca70ab9d92501b84b51427 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 13:59:30 -0700 Subject: [PATCH 19/45] docs(sla): address doc-review consensus (cycle 3) Document create-instance target_reliability binding, align schedule-maint sdate formats, and harden search/rent API examples. Co-authored-by: Cursor --- api-reference/openapi.yaml | 30 ++++++++++++-- .../openapi/yaml/create_instance.yaml | 11 ++++++ .../openapi/yaml/schedule_maint.yaml | 7 +++- api-reference/openapi/yaml/search_offers.yaml | 2 +- cli/reference/search-offers.mdx | 4 +- guides/instances/choosing/sla-coverage.mdx | 39 ++++++++++++------- host/sla-backtester.mdx | 4 +- host/sla-offers.mdx | 18 +++++---- snippets/host/cli/schedule-maint.mdx | 2 +- 9 files changed, 86 insertions(+), 31 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index eba64977..cc47388e 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1648,6 +1648,20 @@ paths: format: float description: 'Size of local disk partition (in GB) + ' + target_reliability: + type: number + format: float + minimum: 0 + exclusiveMaximum: true + description: 'Client SLA coverage target (greater than 0 and less + than 1). When set on an SLA-enabled offer + + (`sla_r_claim > 0`), locks SLA terms on the new contract. Omit + or set to 0 for a non-SLA rental. + + Use the same value you used in search when comparing `dph_total`. + ' runtype: type: string @@ -1774,6 +1788,8 @@ paths: (e.g., `/workspace`) example: image: vastai/base-image:@vastai-automatic-tag + disk: 50 + target_reliability: 0.95 responses: '200': description: Instance created successfully @@ -6367,8 +6383,16 @@ paths: sdate: type: string format: date-time - description: Start date and time of the maintenance window. - example: '2023-10-30T14:00:00Z' + description: 'Start date and time of the maintenance window as an + ISO 8601 UTC datetime + + (for example `2026-08-01T02:00:00Z`). The CLI `--sdate` flag accepts + Unix epoch seconds + + and converts them to this format before calling the API. + + ' + example: '2026-08-01T02:00:00Z' duration: type: integer description: Duration of the maintenance window in hours. @@ -6841,7 +6865,7 @@ paths: ' example: limit: 100 - type: on-demand + type: ondemand verified: eq: true rentable: diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index 9bfbbea2..1306ca66 100644 --- a/api-reference/openapi/yaml/create_instance.yaml +++ b/api-reference/openapi/yaml/create_instance.yaml @@ -63,6 +63,15 @@ paths: format: float description: | Size of local disk partition (in GB) + target_reliability: + type: number + format: float + minimum: 0 + exclusiveMaximum: true + description: | + Client SLA coverage target (greater than 0 and less than 1). When set on an SLA-enabled offer + (`sla_r_claim > 0`), locks SLA terms on the new contract. Omit or set to 0 for a non-SLA rental. + Use the same value you used in search when comparing `dph_total`. runtype: type: string description: | @@ -162,6 +171,8 @@ paths: description: Mount path for the volume inside the container (e.g., `/workspace`) example: image: vastai/base-image:@vastai-automatic-tag + disk: 50 + target_reliability: 0.95 responses: '200': description: Instance created successfully diff --git a/api-reference/openapi/yaml/schedule_maint.yaml b/api-reference/openapi/yaml/schedule_maint.yaml index d8deafed..18b3a1cc 100644 --- a/api-reference/openapi/yaml/schedule_maint.yaml +++ b/api-reference/openapi/yaml/schedule_maint.yaml @@ -37,8 +37,11 @@ paths: sdate: type: string format: date-time - description: Start date and time of the maintenance window. - example: '2023-10-30T14:00:00Z' + description: | + Start date and time of the maintenance window as an ISO 8601 UTC datetime + (for example `2026-08-01T02:00:00Z`). The CLI `--sdate` flag accepts Unix epoch seconds + and converts them to this format before calling the API. + example: '2026-08-01T02:00:00Z' duration: type: integer description: Duration of the maintenance window in hours. diff --git a/api-reference/openapi/yaml/search_offers.yaml b/api-reference/openapi/yaml/search_offers.yaml index 16ab5bbe..b93c497b 100644 --- a/api-reference/openapi/yaml/search_offers.yaml +++ b/api-reference/openapi/yaml/search_offers.yaml @@ -282,7 +282,7 @@ paths: Default is 8GB. example: limit: 100 - type: on-demand + type: ondemand verified: eq: true rentable: diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 731e0a02..b3ee1050 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -44,7 +44,7 @@ vastai search offers [--help] [--api-key API_KEY] [--raw] - New search exp + Use the experimental search path (internal / unstable). Prefer the default search for production and SLA filtering. @@ -151,7 +151,7 @@ vastai search offers 'cpu_arch=arm64' | `reliability` | float | machine reliability score (see FAQ for explanation) | | `expected_reliability` | float | host’s advertised SLA reliability claim on the offer | | `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | -| `target_reliability` | float | your desired SLA coverage level; drives SLA charge in `dph_total` (see [SLA Coverage](/guides/instances/choosing/sla-coverage)) | +| `target_reliability` | float | your desired SLA coverage level (greater than 0 and less than 1); drives SLA charge in `dph_total` (see [SLA Coverage](/guides/instances/choosing/sla-coverage)) | | `rentable` | bool | is the instance currently rentable | | `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances | | `storage_cost` | float | storage cost in $/GB/month | diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 0a4d0677..c6ec7ef0 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -9,7 +9,7 @@ Some Vast.ai offers include a **Service Level Agreement (SLA)** — a reliabilit This page explains SLA from the renter side: how to find SLA offers, how pricing works, and when you get credited. -**SLA is opt-in.** Coverage applies only when you set a reliability target in Search before you rent (console or `target_reliability` in API/CLI). Renting without a target means **no SLA charge and no SLA credits**, even on offers where the host has enabled SLA. +**SLA is opt-in.** In the console, set a reliability target in Search before you rent. Via API/CLI, pass `target_reliability` on **create-instance** (and in search when pricing). Renting without a target means **no SLA charge and no SLA credits**, even on offers where the host has enabled SLA. @@ -44,7 +44,7 @@ total ≈ GPU + storage + bandwidth + SLA charge | --- | --- | | Your reliability target | Higher target → higher SLA charge | | Host SLA claim | Maximum reliability the host advertises on the listing (`expected_reliability`). Higher claim → lower SLA charge at a given target | -| Host confidence | Host pricing setting that affects SLA charge size (tighter = lower charge at a given target) | +| Host confidence | Host-side pricing setting that affects SLA charge size. **Not shown on offer cards** — compare offers using `dph_total` or the SLA charge line in the price breakdown | **Rule of thumb:** pick a target **at or below** the host's claim for the best value. Asking for 99% coverage on a host who only claims 95% costs much more than asking for 95% on a host who claims 99%. @@ -63,9 +63,10 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 ### In the web console 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). -2. In the search filters panel, set your **reliability target** (exact label matches the current UI—typically under advanced or SLA filters). -3. Review offers that show an **SLA charge** line in the price breakdown. If you do not see an SLA charge before clicking **RENT**, you do not have coverage. -4. Rent as usual. Your target is locked at rent time. +2. In the left/top **search filters** panel, find the **reliability target** / SLA filter control (label matches the current UI). Set your target (for example 95%). +3. Optionally filter to SLA-enabled offers if that control is available. +4. Review offers that show an **SLA charge** line in the price breakdown. If you do not see an SLA charge before clicking **RENT**, you do not have coverage. +5. Rent as usual. Your target is locked at rent time. CLI and API examples below use the same filters. @@ -117,10 +118,10 @@ Always compare **`dph_total`**, not just GPU price, when SLA matters. Search ran ### API automation -Searching without `target_reliability`, then calling create-instance on that offer ID, does **not** add SLA retroactively. SLA terms are locked only when `target_reliability` is set in the **same** search request used to select the offer. +SLA coverage is locked at **create-instance** time via `target_reliability` on `PUT /api/v0/asks/{id}/`. Searching with a target only prices offers; renting without passing `target_reliability` on create-instance produces a **non-SLA** contract. -**REST search example** (filter shape differs from CLI query strings — see [Search Offers](/api-reference/search/search-offers)): +**1. Search** (prices `dph_total` at your target — include storage explicitly; REST defaults to 8 GB, CLI `--storage` defaults to 5 GiB): ```bash curl -s -X POST "https://console.vast.ai/api/v0/bundles/" \ @@ -129,19 +130,31 @@ curl -s -X POST "https://console.vast.ai/api/v0/bundles/" \ -d '{ "limit": 20, "type": "ondemand", + "allocated_storage": 50, "target_reliability": {"eq": 0.95}, "has_sla": {"eq": true}, "expected_reliability": {"gte": 0.99} }' ``` -1. **Search** with your target as above (and optionally `has_sla` / `expected_reliability`). -2. **Rent** the chosen offer with `PUT /api/v0/asks/{id}/` ([Create Instance](/api-reference/instances/create-instance)) — no SLA fields on create-instance. -3. **Verify** via show-instances: confirm `target_reliability > 0` and note `search.slaPremiumPerHour`. +**2. Rent** the chosen offer ID and pass the **same** target: -If your automation splits search and rent across workers, pass the search parameters (or offer ID plus confirmed `dph_total` and `target_reliability`) explicitly between steps — do not assume account-wide defaults apply SLA. +```bash +curl -s -X PUT "https://console.vast.ai/api/v0/asks/OFFER_ID/" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "image": "pytorch/pytorch:latest", + "disk": 50, + "target_reliability": 0.95 + }' +``` + +See [Create Instance](/api-reference/instances/create-instance) and [Search Offers](/api-reference/search/search-offers). + +**3. Verify** via show-instances: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. -Hold `--storage` / allocated storage constant when comparing `dph_total` across runs. +Hold `allocated_storage` / `--storage` constant when comparing `dph_total` across runs or between CLI and REST. ## What happens after you rent @@ -209,7 +222,7 @@ Production settlement uses the multi-window reliability blend described above, n Show-instances output may include `target_reliability` and price fields under `search` / `instance` (including `slaPremiumPerHour`). -To find SLA-covered instances, inspect returned objects for `target_reliability > 0` (or filter in your client). The show-instances API does **not** support a `has_sla` query parameter. Where your API key supports it, you may also try `select_filters` on `sla_r_target` / `target_reliability` — see [Show Instances](/api-reference/instances/show-instances). +To find SLA-covered instances, filter client-side from the show-instances response (`target_reliability > 0`, `instance.slaPremiumPerHour`). Server-side `select_filters` on SLA fields is not guaranteed for all API keys — do not depend on it in production automation.
API integrators — field aliases diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 6bac61be..d32c6872 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -57,7 +57,7 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). - The backtester sets claim equal to target and may show higher SLA charges than live listing when clients choose targets below your claim. - For client-visible pricing (`dph_total`), use **Set Pricing → SLA** in the console or search with a realistic `target_reliability`. - For tail risk, trust `worst_day_loss`, not headline `total_sla`. -- Timescale mix (`β`) is derived from `r` for non-admin callers (same default a client targeting `r` would get). Admin overrides of `beta` are ignored for non-admins. +- Timescale mix (`β`) is derived from `r` for non-admin callers (same default a client targeting `r` would get). Hosts cannot set β via the listing API. ## Before you start @@ -91,7 +91,7 @@ Requires Bearer authentication. This endpoint is rate-limited like other host AP | `start_date` | No | Range start as Unix epoch seconds. Default: 90 days before `end_date`. | | `end_date` | No | Range end as Unix epoch seconds. Default: now. | | `reliability` | No | Optional flat uptime override (greater than 0 and at most 1). Ignores historical uptime — useful for what-if analysis. Use `0.01` to approximate near-total downtime; `0` is rejected with `400 bad_request`. | -| `beta` | No | Timescale mix override. For non-admins this is **ignored** — the API derives β from `r` (same default a client targeting `r` would get). Admins may override for analysis. | +| `beta` | No | Ignored for standard API keys — the API derives timescale weighting from `r`. | ### Limits diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index a2607f09..a121461a 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -32,7 +32,7 @@ SLA settlement is **asymmetric by design**: when reliability is strong relative - Confirm SLA is enabled for your account. In the console, open **Set Pricing → SLA** on a machine — if the panel is missing or listing returns `sla_not_approved`, contact [Discord](https://discord.gg/hSuEbSQ4X8) before configuring a fleet. Test one machine before looping fleet scripts. - Ensure your host daemon is current per the [host setup guide](https://cloud.vast.ai/host/setup/). - If listing fails with `sla_not_approved` or `sla_daemon_outdated`, resolve eligibility before changing SLA parameters. -- **Planned maintenance:** SLA credit for scheduled downtime requires the [CLI](/cli/hello-world) (`vastai schedule maint`). If you rely on the web console only, install the CLI before enabling SLA, or accept that planned-maintenance credits may not be available until you do. +- **Planned maintenance:** SLA credit for scheduled downtime requires the [CLI](/cli/hello-world) or [REST schedule-maintenance API](/api-reference/machines/schedule-maint) (`vastai schedule maint`). The web console can configure SLA pricing, but **scheduling maintenance requires CLI or REST**. Install the CLI before enabling SLA if you plan maintenance windows. Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machine appears on **Host → Machines** with no red error status. @@ -425,17 +425,21 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi ### Scheduled maintenance -Maintenance windows scheduled through [`vastai schedule maint`](/host/cli/schedule-maint) may be credited back toward reliability, reducing SLA penalties for planned downtime. Unplanned outages count fully toward SLA settlement. +**Planned SLA maintenance (may earn credit):** Schedule at least 24 hours in advance with [`vastai schedule maint`](/host/cli/schedule-maint) (or the [REST schedule-maintenance API](/api-reference/machines/schedule-maint)). Include `--sdate`, `--duration`, and `--maintenance_category planned`. Credit eligibility is evaluated on a case-by-case basis. -Schedule at least 24 hours ahead when possible: +**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC: ```bash -vastai schedule maint MACHINE_ID --sdate "2026-08-01 02:00:00" --duration 2 +# Example: 2026-08-01 02:00:00 UTC → epoch seconds +# Linux: date -u -d '2026-08-01 02:00:00' +%s +vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 --maintenance_category planned ``` -See [CLI install](/cli/hello-world) if you have not set up the CLI. Credits for planned maintenance are evaluated on a case-by-case basis and are not guaranteed. +REST equivalent: `PUT /api/v0/machines/{machine_id}/dnotify` with `"sdate": "2026-08-01T02:00:00Z"` — see [Schedule Maintenance](/api-reference/machines/schedule-maint). -**Console-only hosts:** install the CLI before enabling SLA if you rely on planned maintenance credits. +**Emergency or unplanned downtime:** Notify clients if possible using `schedule maint`, but expect **full SLA settlement exposure**. Advance-notice credits do not apply to unplanned outages. + +See [CLI install](/cli/hello-world) if you have not set up the CLI. Planned maintenance credit is not guaranteed. The platform evaluates advance notice (generally at least 24 hours recommended) and maintenance duration when determining credit eligibility. **Treat any scheduled downtime as a potential SLA credit event when modeling risk.** Contact support via [Discord](https://discord.gg/hSuEbSQ4X8) or email [contact@vast.ai](mailto:contact@vast.ai) before extended maintenance on an SLA-listed machine to confirm credit eligibility. @@ -511,7 +515,7 @@ Positive `sla_earn` = net SLA charge you kept that period; negative = net credit `GET /api/v0/users/{user_id}/machine-earnings/` returns SLA fields alongside compute earnings. Requires a **`billing_read`** API key. See [`show earnings`](/api-reference/billing/show-earnings). -This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll no faster than about one request every two seconds per IP (`threshold=2.0`); back off on HTTP 429. +This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/rate-limits-and-errors). Poll at most about once every two seconds per IP; back off on HTTP 429. When you pass `machid`, use `per_machine[].sla_earn` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 4c15dee8..8eb31ae9 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -19,7 +19,7 @@ vastai schedule maint id [--sdate START_DATE --duration DURATION --maintenance_c ## Options - maintenance start date in unix epoch time (UTC seconds) + Maintenance start time as Unix epoch seconds (UTC). Example: `1677562671`. The API receives an ISO 8601 UTC datetime after conversion. From b9534b9d7f14c0cd567fb32879f1dde1d73707fa Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 14:04:34 -0700 Subject: [PATCH 20/45] docs(sla): address doc-review consensus (cycle 4) Align schedule-maint category and framing with the API enum; clarify console SLA filter and outage billing. Co-authored-by: Cursor --- api-reference/openapi.yaml | 5 +-- .../openapi/yaml/schedule_maint.yaml | 4 +-- .../openapi/yaml/show_instances.yaml | 2 +- guides/instances/choosing/sla-coverage.mdx | 25 +++++++------ host/hosting-overview.mdx | 35 +++++-------------- host/sla-offers.mdx | 7 ++-- snippets/host/cli/schedule-maint.mdx | 25 ++++++++++--- 7 files changed, 53 insertions(+), 50 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index cc47388e..3c7d12d7 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -8095,8 +8095,9 @@ paths: present). Computed fields (e.g. `dph_total`, `num_gpus`, `has_sla`) are not filterable and return 400. - To find SLA-covered instances, filter client-side on `target_reliability - > 0` or use `select_filters` on `sla_r_target` if supported for your key. + Prefer client-side filtering on `target_reliability > 0` for SLA-covered + instances. Optional `select_filters` on stored SLA fields may work for some + keys; do not rely on it as the only detection path. ' schema: diff --git a/api-reference/openapi/yaml/schedule_maint.yaml b/api-reference/openapi/yaml/schedule_maint.yaml index 18b3a1cc..447ab2c6 100644 --- a/api-reference/openapi/yaml/schedule_maint.yaml +++ b/api-reference/openapi/yaml/schedule_maint.yaml @@ -131,5 +131,5 @@ x-cli-commands: description: Schedule maintenance for a machine. endpoint: /api/v0/machines/{machine_id}/dnotify method: PUT - example: vast-ai schedule maint 12345 --sdate "2023-10-30T14:00:00Z" --duration - 2 + example: vastai schedule maint 12345 --sdate 1698674400 --duration 2 + --maintenance_category software diff --git a/api-reference/openapi/yaml/show_instances.yaml b/api-reference/openapi/yaml/show_instances.yaml index 88f4bf83..08f768fc 100644 --- a/api-reference/openapi/yaml/show_instances.yaml +++ b/api-reference/openapi/yaml/show_instances.yaml @@ -56,7 +56,7 @@ paths: JSON object of column filters. Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notin`. Filterable columns: `actual_status`, `gpu_name`, `verification`, `id`, `label`, and other columns stored directly on the contract record (including `sla_r_claim` and `sla_r_target` / `target_reliability` when present). Computed fields (e.g. `dph_total`, `num_gpus`, `has_sla`) are not filterable and return 400. - To find SLA-covered instances, filter client-side on `target_reliability > 0` or use `select_filters` on `sla_r_target` if supported for your key. + Prefer client-side filtering on `target_reliability > 0` for SLA-covered instances. Optional `select_filters` on stored SLA fields may work for some keys; do not rely on it as the only detection path. schema: type: string default: '{}' diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index c6ec7ef0..8a45fce6 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -63,9 +63,9 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 ### In the web console 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). -2. In the left/top **search filters** panel, find the **reliability target** / SLA filter control (label matches the current UI). Set your target (for example 95%). +2. In the **search filters** panel, set **Reliability target** (or the current SLA / reliability filter control) to your desired level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. 3. Optionally filter to SLA-enabled offers if that control is available. -4. Review offers that show an **SLA charge** line in the price breakdown. If you do not see an SLA charge before clicking **RENT**, you do not have coverage. +4. Before you click **RENT**, confirm the price breakdown shows an **SLA charge** line. No SLA charge means no SLA coverage for that rental. 5. Rent as usual. Your target is locked at rent time. CLI and API examples below use the same filters. @@ -167,7 +167,11 @@ When you rent an SLA-backed offer **with a target set**: ### What you pay during an outage -You are still charged for **compute and the SLA charge** for the rental day while the instance is unavailable. If you qualify for compensation, a **settlement credit** is applied after daily settlement (UTC), typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. + +Billing continues during downtime. You are still charged for **compute, storage, and the SLA charge** while the contract exists and the instance is unavailable. Leaving a broken instance running continues those charges until you destroy it. + + +If you qualify for compensation, a **settlement credit** is applied after daily settlement (UTC), typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. Destroying ends future daily charges; final SLA settlement still posts when the contract closes. ### How reliability is measured @@ -177,7 +181,7 @@ Each day, the platform tracks how long your instance was online. Settlement cons - A pattern of unreliable uptime produces larger credits over time. - One strong day after a weak week does not instantly reset everything. -Scheduled maintenance with adequate notice may be credited toward reliability. Unplanned outages count fully. +Scheduled maintenance with adequate advance notice (typically 24+ hours) may be credited toward reliability on a case-by-case basis. Check **Instances** status and any client notifications during downtime to distinguish planned maintenance from an unexpected outage. Unplanned outages count fully. ### Credit scenarios (simplified) @@ -222,19 +226,18 @@ Production settlement uses the multi-window reliability blend described above, n Show-instances output may include `target_reliability` and price fields under `search` / `instance` (including `slaPremiumPerHour`). -To find SLA-covered instances, filter client-side from the show-instances response (`target_reliability > 0`, `instance.slaPremiumPerHour`). Server-side `select_filters` on SLA fields is not guaranteed for all API keys — do not depend on it in production automation. +To find SLA-covered instances, filter **client-side** from the show-instances response (`target_reliability > 0`, `instance.slaPremiumPerHour`). Prefer client-side filtering in production. OpenAPI documents optional `select_filters` on stored fields such as `sla_r_target` / `target_reliability` when present; computed fields (for example `has_sla`) are not filterable. Do not rely on `select_filters` alone for SLA detection.
-API integrators — field aliases +API integrators — response field names (parsers only; console users can skip) -| Console / concept | API / raw field | +| Client-visible concept | API / raw field | | --- | --- | -| Host SLA claim | `expected_reliability` on offers; `sla_r_claim` on contracts | -| Host confidence | `sla_sigma_x` | +| Your reliability target | `target_reliability` | | SLA charge rate | `search.slaPremiumPerHour` / `instance.slaPremiumPerHour` | -| Your target | `target_reliability` | +| Host SLA claim (offers / contracts) | `expected_reliability` / `sla_r_claim` | -These fields appear in CLI `--raw` output when SLA is active. Confirm against a live `--raw` response before building parsers. +Host confidence is a host-side pricing setting and is **not shown on offer cards** — compare offers using `dph_total` or the SLA charge line. Confirm field names against a live `--raw` response before building parsers.
## When SLA is not available diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 8caac1fd..f93c8a60 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -231,28 +231,17 @@ You can then look at your [instance tab](https://cloud.vast.ai/instances/) to ma ## Maintenance -The proper way to perform maintenance on your machine is to wait until all active rental contracts have ended or the machine has no running instances. - -Unlisting the offer will prevent new rental contracts from being created, but does not affect existing ones. However if you have active rental contracts, you could set the offer end date to match the latest rental end date, allowing new clients to rent instances that end at the same date. Once the end date is reached, you can then unlist the machine and then perform maintenance. - Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored. -You have two maintenance paths: - -1. **After contracts end:** Take the machine offline once every active rental contract has ended (default path). -2. **During active SLA contracts:** Use planned maintenance via [`vastai schedule maint`](/host/cli/schedule-maint) with at least 24 hours’ notice. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance) for credit rules. - -For unplanned or unscheduled maintenance, use the CLI and the [`vastai schedule maint`](/host/cli/schedule-maint) command. That will notify the client that you **have** to take the machine down and that they should save their work. You can specify a date and duration. +Unlisting the offer prevents new rentals but does not end existing ones. If you have active contracts, you can set the offer end date to match the latest rental end date so new clients rent instances that end together. Once that date is reached, unlist and perform maintenance. -### If you have SLA enabled on this machine +Use these paths in order: -SLA-listed machines have additional maintenance obligations: +1. **Preferred (no active renters):** Wait until all contracts have ended, then take the machine offline. +2. **Planned SLA maintenance (active renters):** If SLA is enabled, use [`vastai schedule maint`](/host/cli/schedule-maint) with a start time at least 24 hours in the future. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance) for credit eligibility. +3. **Emergency or unplanned downtime:** Use [`vastai schedule maint`](/host/cli/schedule-maint) immediately to notify renters. Full SLA settlement exposure may apply. -- Give at least **24 hours' notice** before planned downtime when possible. -- Use [`vastai schedule maint`](/host/cli/schedule-maint) and configure [Host Notifications](/host/notifications) for `host:maintenance_scheduled` if you want your own alerts. -- Uptime credits during maintenance are evaluated case by case — see [Scheduled maintenance](/host/sla-offers#scheduled-maintenance). - -General maintenance guidance above applies to all hosts regardless of SLA. +The same `schedule maint` command supports planned and emergency notifications; advance notice and duration determine SLA credit eligibility. Optional: configure [Host Notifications](/host/notifications) for `host:maintenance_scheduled`. ## Uninstalling @@ -268,17 +257,15 @@ Hosting on Vast will require some Linux knowledge, as you will be maintaining a You can create an invoice by going to the "Billing" page, and then click the box for "Include Charges" under "Generate Billing History". -### Why can't I find my machine in search? +### Why can't I find my machine in search? / Why is my machine not listed? If your machine seems unlisted or missing from console search: -- Confirm **Listed** status on **Host → Machines**. -- **CLI check:** `vastai search offers 'machine_id=MACHINE_ID verified=any'` — if this returns a result, your machine is listed. +- Confirm **Listed** status on **Host → Machines** (console). +- **CLI check:** `vastai search offers 'machine_id=MACHINE_ID verified=any'` — if this returns a result, your machine is listed. The GUI may lag behind CLI visibility. - Individual machines can be hard to find in broad console search; looking up by `machine_id` is the reliable check. - **Ranking check:** Use narrow filters to see similar machines, e.g. `vastai search offers 'gpu_name=RTX_4090 cpu_ram>257 cpu_ram<258'`. -See also [Why is my machine not listed?](#why-is-my-machine-not-listed) below. - ### Can you verify my machine? Verification is conducted in a randomized and automated fashion. We only run manual verification tests for datacenters and high-end machines. @@ -299,10 +286,6 @@ You can use the [uninstall script](https://s3.amazonaws.com/vast.ai/uninstall) If the hosting software detects an error, that error message will be listed on your machine in the machines page. Once the cause of the error has been resolved, most error messages will be automatically cleared after 1-2 hours. The quickest way to learn more about resolving specific error messages is to check out the hosting channels in [our discord](https://discord.gg/hSuEbSQ4X8). -### Why is my machine not listed? - -You won't be able to see it on the GUI right away, but you can search using the [CLI](/guides/instances/managing-instances). See [Why can't I find my machine in search?](#why-cant-i-find-my-machine-in-search) above for the full checklist. - ### Can I send a message to a client using my machine letting them know that I fixed an issue that they were having? No, there is not an established process for hosts to message clients on Vast. diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index a121461a..5fea42bc 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -425,14 +425,15 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi ### Scheduled maintenance -**Planned SLA maintenance (may earn credit):** Schedule at least 24 hours in advance with [`vastai schedule maint`](/host/cli/schedule-maint) (or the [REST schedule-maintenance API](/api-reference/machines/schedule-maint)). Include `--sdate`, `--duration`, and `--maintenance_category planned`. Credit eligibility is evaluated on a case-by-case basis. +**Planned SLA maintenance (may earn credit):** Schedule at least 24 hours in advance with [`vastai schedule maint`](/host/cli/schedule-maint) (or the [REST schedule-maintenance API](/api-reference/machines/schedule-maint)). Include `--sdate` and `--duration`. Advance notice (not the category value) is what makes maintenance “planned” for SLA credit review. Valid `--maintenance_category` values: `power`, `internet`, `disk`, `gpu`, `software`, `other`. Credit eligibility is evaluated on a case-by-case basis. -**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC: +**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC. **CLI `--duration` is in hours.** ```bash # Example: 2026-08-01 02:00:00 UTC → epoch seconds # Linux: date -u -d '2026-08-01 02:00:00' +%s -vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 --maintenance_category planned +vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 \ + --maintenance_category software --maintenance_reason "OS kernel upgrade" ``` REST equivalent: `PUT /api/v0/machines/{machine_id}/dnotify` with `"sdate": "2026-08-01T02:00:00Z"` — see [Schedule Maintenance](/api-reference/machines/schedule-maint). diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 8eb31ae9..2c44b664 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -32,16 +32,31 @@ vastai schedule maint id [--sdate START_DATE --duration DURATION --maintenance_c ## Description -The proper way to perform maintenance on your machine is to wait until all active contracts have expired or the machine is vacant. -For unplanned or unscheduled maintenance, use this schedule maint command. That will notify the client that you have to take the machine down and that they should save their work. -You can specify a date, duration, reason and category for the maintenance. +The lowest-risk path is to wait until all active contracts have expired or the machine is vacant, then take the machine offline. -Example: vastai schedule maint 8207 `--sdate` 1677562671 `--duration` 0.5 `--maintenance_category` "power" +The same `schedule maint` command is used for both **planned** and **emergency** downtime — advance notice and duration determine SLA credit eligibility, not the category value. + +### Planned SLA maintenance + +If SLA is enabled and you need planned downtime during an active rental, schedule at least 24 hours in advance. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance). + +```bash +vastai schedule maint 8207 --sdate 1785549600 --duration 2 \ + --maintenance_category software --maintenance_reason "OS kernel upgrade" +``` + +### Emergency or unplanned maintenance + +If the machine must go offline without adequate notice, still run `schedule maint` to notify renters — but expect full SLA settlement exposure when SLA is enabled. + +```bash +vastai schedule maint 8207 --sdate 1677562671 --duration 0.5 --maintenance_category power +``` ## Examples ```bash -vastai schedule maint +vastai schedule maint --sdate --duration --maintenance_category software ``` ## Global Options From c19b8a165f2590c053bae65e8ad2c90f9ae0fe96 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 14:08:56 -0700 Subject: [PATCH 21/45] docs(sla): address doc-review consensus (cycle 5) Clarify CLI create-instance lacks target_reliability; document REST-only maintenance_reason and raise maintenance tooling prerequisite. Co-authored-by: Cursor --- guides/instances/choosing/sla-coverage.mdx | 22 +++++++++++++++------- host/sla-offers.mdx | 14 +++++++++----- snippets/host/cli/schedule-maint.mdx | 7 +++++-- 3 files changed, 29 insertions(+), 14 deletions(-) diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 8a45fce6..078f5a15 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -9,7 +9,11 @@ Some Vast.ai offers include a **Service Level Agreement (SLA)** — a reliabilit This page explains SLA from the renter side: how to find SLA offers, how pricing works, and when you get credited. -**SLA is opt-in.** In the console, set a reliability target in Search before you rent. Via API/CLI, pass `target_reliability` on **create-instance** (and in search when pricing). Renting without a target means **no SLA charge and no SLA credits**, even on offers where the host has enabled SLA. +**SLA is opt-in.** In the console, set a reliability target in Search before you rent. Via the **REST API**, pass `target_reliability` on **create-instance** (`PUT /api/v0/asks/{id}/`). Renting without a target means **no SLA charge and no SLA credits**, even on offers where the host has enabled SLA. + + +`target_reliability` is **not yet** available on the published `vastai create instance` CLI or Python SDK `create_instance()`. Searching with `target_reliability` only affects quoted pricing — it does **not** enable SLA on the contract unless you pass the same value at create-instance via **REST** or the **web console**. + @@ -63,7 +67,7 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 ### In the web console 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). -2. In the **search filters** panel, set **Reliability target** (or the current SLA / reliability filter control) to your desired level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. +2. In Search filters (left filter bar), set **Reliability target** to your desired coverage level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. 3. Optionally filter to SLA-enabled offers if that control is available. 4. Before you click **RENT**, confirm the price breakdown shows an **SLA charge** line. No SLA charge means no SLA coverage for that rental. 5. Rent as usual. Your target is locked at rent time. @@ -118,7 +122,7 @@ Always compare **`dph_total`**, not just GPU price, when SLA matters. Search ran ### API automation -SLA coverage is locked at **create-instance** time via `target_reliability` on `PUT /api/v0/asks/{id}/`. Searching with a target only prices offers; renting without passing `target_reliability` on create-instance produces a **non-SLA** contract. +SLA coverage is locked at **create-instance** time via `target_reliability` on `PUT /api/v0/asks/{id}/` (REST). Searching with a target only prices offers. The published CLI/SDK create-instance path does **not** accept `target_reliability` yet — use REST or the console to rent with SLA. **1. Search** (prices `dph_total` at your target — include storage explicitly; REST defaults to 8 GB, CLI `--storage` defaults to 5 GiB): @@ -171,7 +175,9 @@ When you rent an SLA-backed offer **with a target set**: Billing continues during downtime. You are still charged for **compute, storage, and the SLA charge** while the contract exists and the instance is unavailable. Leaving a broken instance running continues those charges until you destroy it. -If you qualify for compensation, a **settlement credit** is applied after daily settlement (UTC), typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. Destroying ends future daily charges; final SLA settlement still posts when the contract closes. +**Stop vs destroy:** Stopping pauses compute but storage and contract charges can continue. **Destroying the instance** ends future daily charges; final SLA settlement still posts when the contract closes. If you abandon a failed host, destroy only after saving any data you need. + +If you qualify for compensation, a **settlement credit** is applied after daily settlement (UTC), typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. ### How reliability is measured @@ -224,13 +230,15 @@ Production settlement uses the multi-window reliability blend described above, n ### API / CLI +Console users: open **Instances** → select your instance → **price details** to confirm the SLA charge and target. Skip the block below if you do not use the API. + +
+API integrators: field names and filters + Show-instances output may include `target_reliability` and price fields under `search` / `instance` (including `slaPremiumPerHour`). To find SLA-covered instances, filter **client-side** from the show-instances response (`target_reliability > 0`, `instance.slaPremiumPerHour`). Prefer client-side filtering in production. OpenAPI documents optional `select_filters` on stored fields such as `sla_r_target` / `target_reliability` when present; computed fields (for example `has_sla`) are not filterable. Do not rely on `select_filters` alone for SLA detection. -
-API integrators — response field names (parsers only; console users can skip) - | Client-visible concept | API / raw field | | --- | --- | | Your reliability target | `target_reliability` | diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 5fea42bc..0438df8f 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -27,12 +27,17 @@ SLA settlement is **asymmetric by design**: when reliability is strong relative ## Before you enable SLA + +If you expect downtime during active rentals, install the [Vast CLI](/cli/hello-world) (or plan to use the [REST schedule-maintenance API](/api-reference/machines/schedule-maint)) **before** enabling SLA. Planned SLA maintenance must be scheduled at least 24 hours ahead via CLI or REST — there is no in-console maintenance scheduler today. + + **Pre-flight checklist (before tuning claim/confidence):** -- Confirm SLA is enabled for your account. In the console, open **Set Pricing → SLA** on a machine — if the panel is missing or listing returns `sla_not_approved`, contact [Discord](https://discord.gg/hSuEbSQ4X8) before configuring a fleet. Test one machine before looping fleet scripts. +- Hosting requires a separate host account and hosting agreement — see [Account setup](/host/hosting-overview#account-setup-and-hosting-agreement) if you have not completed host onboarding. +- Confirm SLA is enabled for your account. In the console, open **Set Pricing → SLA** on a machine — if the panel is missing or listing returns `sla_not_approved`, contact [Discord](https://discord.gg/hSuEbSQ4X8) or [contact@vast.ai](mailto:contact@vast.ai) to request access before configuring a fleet. Approval timing varies; complete host setup and a base listing first. - Ensure your host daemon is current per the [host setup guide](https://cloud.vast.ai/host/setup/). - If listing fails with `sla_not_approved` or `sla_daemon_outdated`, resolve eligibility before changing SLA parameters. -- **Planned maintenance:** SLA credit for scheduled downtime requires the [CLI](/cli/hello-world) or [REST schedule-maintenance API](/api-reference/machines/schedule-maint) (`vastai schedule maint`). The web console can configure SLA pricing, but **scheduling maintenance requires CLI or REST**. Install the CLI before enabling SLA if you plan maintenance windows. +- **Planned maintenance tooling:** Use [`vastai schedule maint`](/host/cli/schedule-maint) or REST — see [Scheduled maintenance](#scheduled-maintenance). Complete [host setup](https://cloud.vast.ai/host/setup/) first. A healthy machine appears on **Host → Machines** with no red error status. @@ -432,11 +437,10 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi ```bash # Example: 2026-08-01 02:00:00 UTC → epoch seconds # Linux: date -u -d '2026-08-01 02:00:00' +%s -vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 \ - --maintenance_category software --maintenance_reason "OS kernel upgrade" +vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 --maintenance_category software ``` -REST equivalent: `PUT /api/v0/machines/{machine_id}/dnotify` with `"sdate": "2026-08-01T02:00:00Z"` — see [Schedule Maintenance](/api-reference/machines/schedule-maint). +REST equivalent: `PUT /api/v0/machines/{machine_id}/dnotify` with `"sdate": "2026-08-01T02:00:00Z"` (optional `"maintenance_reason": "OS kernel upgrade"`) — see [Schedule Maintenance](/api-reference/machines/schedule-maint). **Emergency or unplanned downtime:** Notify clients if possible using `schedule maint`, but expect **full SLA settlement exposure**. Advance-notice credits do not apply to unplanned outages. diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 2c44b664..3c27f94f 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -30,6 +30,10 @@ vastai schedule maint id [--sdate START_DATE --duration DURATION --maintenance_c (optional) can be one of [power, internet, disk, gpu, software, other] + +Optional REST body field `maintenance_reason` (short description for notifications) is available on [Schedule Maintenance](/api-reference/machines/schedule-maint). The published CLI does not yet expose a `--maintenance_reason` flag. + + ## Description The lowest-risk path is to wait until all active contracts have expired or the machine is vacant, then take the machine offline. @@ -41,8 +45,7 @@ The same `schedule maint` command is used for both **planned** and **emergency** If SLA is enabled and you need planned downtime during an active rental, schedule at least 24 hours in advance. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance). ```bash -vastai schedule maint 8207 --sdate 1785549600 --duration 2 \ - --maintenance_category software --maintenance_reason "OS kernel upgrade" +vastai schedule maint 8207 --sdate 1785549600 --duration 2 --maintenance_category software ``` ### Emergency or unplanned maintenance From 68f2456e1a71e5a53a0d9e3ca478cc248510615f Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 14:14:00 -0700 Subject: [PATCH 22/45] docs(sla): address doc-review consensus (cycle 6) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Harden search→rent SLA handoff, schedule-maint examples, earnings day indices, and create-instance error guidance. Co-authored-by: Cursor --- api-reference/openapi.yaml | 14 ++++++++++++-- api-reference/openapi/yaml/show_earnings.yaml | 8 ++++++-- cli/reference/search-offers.mdx | 7 +++++-- guides/instances/choosing/sla-coverage.mdx | 11 ++++++++++- host/sla-backtester.mdx | 4 ++-- host/sla-offers.mdx | 4 ++-- snippets/host/cli/schedule-maint.mdx | 14 ++++++++------ 7 files changed, 45 insertions(+), 17 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 3c7d12d7..795d97a0 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -7907,12 +7907,22 @@ paths: in: query schema: type: integer - description: Start day for the earnings report. + description: 'Start day for the earnings report as a UTC day index: + + `floor(unix_epoch_seconds / 86400)`. Prefer `last_days` when you do not + need an absolute window. + + ' - name: eday in: query schema: type: integer - description: End day for the earnings report. + description: 'End day for the earnings report as a UTC day index: + + `floor(unix_epoch_seconds / 86400)` (inclusive end of the window when used + with `sday`). + + ' - name: machid in: query schema: diff --git a/api-reference/openapi/yaml/show_earnings.yaml b/api-reference/openapi/yaml/show_earnings.yaml index 5fe90ee1..2bee32a4 100644 --- a/api-reference/openapi/yaml/show_earnings.yaml +++ b/api-reference/openapi/yaml/show_earnings.yaml @@ -30,12 +30,16 @@ paths: in: query schema: type: integer - description: Start day for the earnings report. + description: | + Start day for the earnings report as a UTC day index: + `floor(unix_epoch_seconds / 86400)`. Prefer `last_days` when you do not need an absolute window. - name: eday in: query schema: type: integer - description: End day for the earnings report. + description: | + End day for the earnings report as a UTC day index: + `floor(unix_epoch_seconds / 86400)` (inclusive end of the window when used with `sday`). - name: machid in: query schema: diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index b3ee1050..16f47c49 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -44,7 +44,7 @@ vastai search offers [--help] [--api-key API_KEY] [--raw] - Use the experimental search path (internal / unstable). Prefer the default search for production and SLA filtering. + Experimental search path — not recommended for production use. Prefer the default search for SLA filtering. @@ -82,6 +82,9 @@ bool = True | False vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False' # SLA offers: host claim ≥ 99%, your coverage target 95% (see SLA Coverage) +# Search pricing only — target_reliability here quotes dph_total; it does not enable SLA on rent. +# To cover a rental: console Search target, or REST create-instance with target_reliability. +# vastai create instance does not support SLA yet. vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --order dph_total # datacenter GPUs with minimum compute capability and TFLOPs @@ -151,7 +154,7 @@ vastai search offers 'cpu_arch=arm64' | `reliability` | float | machine reliability score (see FAQ for explanation) | | `expected_reliability` | float | host’s advertised SLA reliability claim on the offer | | `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | -| `target_reliability` | float | your desired SLA coverage level (greater than 0 and less than 1); drives SLA charge in `dph_total` (see [SLA Coverage](/guides/instances/choosing/sla-coverage)) | +| `target_reliability` | float | your desired SLA coverage level (greater than 0 and less than 1); drives SLA charge in `dph_total` for **search quotes only**. Pass the same value at create-instance via console or REST to enable coverage — `vastai create instance` does not support SLA yet (see [SLA Coverage](/guides/instances/choosing/sla-coverage)) | | `rentable` | bool | is the instance currently rentable | | `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances | | `storage_cost` | float | storage cost in $/GB/month | diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 078f5a15..a07c4475 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -68,7 +68,7 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). 2. In Search filters (left filter bar), set **Reliability target** to your desired coverage level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. -3. Optionally filter to SLA-enabled offers if that control is available. +3. Optionally filter to SLA-enabled offers (`has_sla` / SLA-enabled control) if available — separate from **Reliability target**. 4. Before you click **RENT**, confirm the price breakdown shows an **SLA charge** line. No SLA charge means no SLA coverage for that rental. 5. Rent as usual. Your target is locked at rent time. @@ -156,8 +156,17 @@ curl -s -X PUT "https://console.vast.ai/api/v0/asks/OFFER_ID/" \ See [Create Instance](/api-reference/instances/create-instance) and [Search Offers](/api-reference/search/search-offers). +**API key permissions:** create a scoped key with `misc` (search/bundles), `instance_write` (create-instance), and preferably `instance_read` (verify show-instances). See [Authentication](/api-reference/authentication) and [Permissions](/api-reference/permissions). + **3. Verify** via show-instances: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. +| Symptom | Typical response | What to do | +| --- | --- | --- | +| Target on a non-SLA offer | HTTP 400 `invalid_args` | Search with `has_sla=true`; confirm `expected_reliability` | +| Target out of range / invalid | HTTP 400 `invalid_args` | Use `0 < target_reliability < 1`; stay at or below a realistic host claim | +| Offer gone / not rentable | HTTP 404/410 `no_such_ask` | Re-search and rent a current offer ID | +| Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage, then rent again | + Hold `allocated_storage` / `--storage` constant when comparing `dph_total` across runs or between CLI and REST. ## What happens after you rent diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index d32c6872..6ddcc8c1 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -57,7 +57,7 @@ For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). - The backtester sets claim equal to target and may show higher SLA charges than live listing when clients choose targets below your claim. - For client-visible pricing (`dph_total`), use **Set Pricing → SLA** in the console or search with a realistic `target_reliability`. - For tail risk, trust `worst_day_loss`, not headline `total_sla`. -- Timescale mix (`β`) is derived from `r` for non-admin callers (same default a client targeting `r` would get). Hosts cannot set β via the listing API. +- Timescale mix (`β`) is derived from `r` (weights recent vs longer-term uptime in settlement). Hosts cannot set β via the listing API. ## Before you start @@ -91,7 +91,7 @@ Requires Bearer authentication. This endpoint is rate-limited like other host AP | `start_date` | No | Range start as Unix epoch seconds. Default: 90 days before `end_date`. | | `end_date` | No | Range end as Unix epoch seconds. Default: now. | | `reliability` | No | Optional flat uptime override (greater than 0 and at most 1). Ignores historical uptime — useful for what-if analysis. Use `0.01` to approximate near-total downtime; `0` is rejected with `400 bad_request`. | -| `beta` | No | Ignored for standard API keys — the API derives timescale weighting from `r`. | +| `beta` | No | Not user-configurable — the API derives timescale weighting from `r`. | ### Limits diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 0438df8f..34ce73e4 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -20,7 +20,7 @@ SLA settlement is **asymmetric by design**: when reliability is strong relative | Goal | Start here | | --- | --- | -| Preview economics and enable SLA in the console | [How it works](#how-it-works-plain-english) → [Listing an SLA offer](#listing-an-sla-offer) | +| Preview economics and enable SLA in the console | [How it works](#how-it-works-plain-english) → [Listing an SLA offer](#listing-an-sla-offer). Planned downtime during active rentals still needs [CLI/REST schedule maint](#scheduled-maintenance) — no in-console scheduler. | | Enable or update SLA via API | [Before you enable SLA](#before-you-enable-sla) → [API (for automation)](#api-for-automation) | | I list with CLI only (no SLA flags yet) | **Set Pricing → SLA** + **LIST** in the console, or REST `PUT /api/v0/machines/create_asks/` — SLA flags are **not** in `vastai list machine` yet | | Monitor settlement after listing | [Monitoring SLA after listing](#monitoring-sla-after-listing) | @@ -526,7 +526,7 @@ This endpoint is rate-limited — see [Rate Limits and Errors](/api-reference/ra When you pass `machid`, use `per_machine[].sla_earn` for that machine's SLA settlement in the window. Do **not** read `per_day[].sla_earn` for single-machine checks — `per_day[]` is always fleet-wide, even with `?machid=`. **Quick rules:** -- **One machine, one UTC day:** use `last_days=1` with `machid` set, or `sday`/`eday` (UTC day indices). +- **One machine, one UTC day:** use `last_days=1` with `machid` set, or `sday`/`eday` as UTC day indices (`day = floor(unix_epoch_seconds / 86400)`). Example: for `2026-07-24` UTC, `sday=eday=20658`. Prefer `last_days` when you do not need an absolute window. - **Fleet snapshot:** one request without `machid` returns all machines in `per_machine[]` for the window: ```bash diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 3c27f94f..e3f28613 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -1,6 +1,6 @@ -Schedule upcoming maint window +Schedule an upcoming maintenance window -This is a **host** command, used for managing machines you are renting out on Vast.ai. +This is a **host** command, used for managing machines you are renting out on Vast.ai. First time? Install the CLI via [CLI hello world](/cli/hello-world), then confirm with `vastai --help`. ## Usage @@ -23,7 +23,7 @@ vastai schedule maint id [--sdate START_DATE --duration DURATION --maintenance_c - maintenance duration in hours + Maintenance duration in hours. Prefer whole hours for REST compatibility (OpenAPI `duration` is an integer). The CLI may accept fractional values (for example `0.5`). @@ -45,15 +45,17 @@ The same `schedule maint` command is used for both **planned** and **emergency** If SLA is enabled and you need planned downtime during an active rental, schedule at least 24 hours in advance. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance). ```bash -vastai schedule maint 8207 --sdate 1785549600 --duration 2 --maintenance_category software +# Replace MACHINE_ID; set --sdate to a future UTC epoch (≥24h ahead for planned credit review) +# Linux: date -u -d '2026-08-01 02:00:00' +%s +vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 --maintenance_category software ``` ### Emergency or unplanned maintenance -If the machine must go offline without adequate notice, still run `schedule maint` to notify renters — but expect full SLA settlement exposure when SLA is enabled. +If the machine must go offline without adequate notice, still run `schedule maint` to notify renters — but expect full SLA settlement exposure when SLA is enabled. Use the current UTC epoch for `--sdate` and an integer `--duration` (hours): ```bash -vastai schedule maint 8207 --sdate 1677562671 --duration 0.5 --maintenance_category power +vastai schedule maint MACHINE_ID --sdate "$(date -u +%s)" --duration 1 --maintenance_category power ``` ## Examples From d7cf43fc2a4d3ebbaba422ec7007a5207caca528 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 14:18:08 -0700 Subject: [PATCH 23/45] docs(sla): address doc-review consensus (cycle 7) Strip CMS frontmatter, align storage/beta/OpenAPI notes, and fix create-instance error codes for integrators. Co-authored-by: Cursor --- api-reference/openapi.yaml | 6 +++--- api-reference/openapi/yaml/sla_backtest.yaml | 5 ++++- cli/reference/search-offers.mdx | 3 ++- guides/instances/choosing/sla-coverage.mdx | 19 +++++++++++++++---- host/hosting-overview.mdx | 6 +++--- 5 files changed, 27 insertions(+), 12 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 795d97a0..a589de1c 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -9312,9 +9312,9 @@ paths: type: number format: float default: 0.5 - description: "Timescale mix override. For non-admins this is ignored \u2014\ - \ the API derives beta from r (same default a client targeting r would get).\ - \ Admins may override for analysis." + description: "Timescale mix used in settlement simulation. Not user-configurable\ + \ for host API keys \u2014\nthe API derives weighting from `r` (recent vs\ + \ longer-term uptime). Omit this parameter.\n" responses: '200': description: Successful response diff --git a/api-reference/openapi/yaml/sla_backtest.yaml b/api-reference/openapi/yaml/sla_backtest.yaml index eab06390..162264cd 100644 --- a/api-reference/openapi/yaml/sla_backtest.yaml +++ b/api-reference/openapi/yaml/sla_backtest.yaml @@ -71,7 +71,10 @@ paths: type: number format: float default: 0.5 - description: Timescale mix override. For non-admins this is ignored — the API derives beta from r (same default a client targeting r would get). Admins may override for analysis. + description: | + Timescale mix used in settlement simulation. Not user-configurable for host API keys — + the API derives weighting from `r` (recent vs longer-term uptime). Omit this parameter. + responses: '200': description: Successful response diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 16f47c49..d048b8ae 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -85,7 +85,8 @@ vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=Fal # Search pricing only — target_reliability here quotes dph_total; it does not enable SLA on rent. # To cover a rental: console Search target, or REST create-instance with target_reliability. # vastai create instance does not support SLA yet. -vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --order dph_total +# Always set --storage explicitly (CLI default 5 GiB; REST search default 8 GB) when comparing dph_total. +vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --storage 50 --order dph_total # datacenter GPUs with minimum compute capability and TFLOPs vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True' diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index a07c4475..2d3507b7 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -14,6 +14,14 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing `target_reliability` is **not yet** available on the published `vastai create instance` CLI or Python SDK `create_instance()`. Searching with `target_reliability` only affects quoted pricing — it does **not** enable SLA on the contract unless you pass the same value at create-instance via **REST** or the **web console**. + +## Choose your path + +| Goal | Start here | +| --- | --- | +| Rent with SLA in the console | [Finding SLA offers → In the web console](#in-the-web-console) | +| Understand charges and credits | [How pricing works](#how-pricing-works) → [What happens after you rent](#what-happens-after-you-rent) | +| Automate search → rent → verify | [API automation](#api-automation) (REST; CLI cannot rent with SLA yet) | @@ -68,7 +76,7 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). 2. In Search filters (left filter bar), set **Reliability target** to your desired coverage level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. -3. Optionally filter to SLA-enabled offers (`has_sla` / SLA-enabled control) if available — separate from **Reliability target**. +3. Optionally narrow to host SLA listings with an SLA-enabled / `has_sla` filter if shown. That filter only restricts which offers appear — it does **not** replace setting **Reliability target**. If you do not see a separate SLA toggle, set Reliability target and confirm the SLA charge line before rent. 4. Before you click **RENT**, confirm the price breakdown shows an **SLA charge** line. No SLA charge means no SLA coverage for that rental. 5. Rent as usual. Your target is locked at rent time. @@ -164,8 +172,9 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe | --- | --- | --- | | Target on a non-SLA offer | HTTP 400 `invalid_args` | Search with `has_sla=true`; confirm `expected_reliability` | | Target out of range / invalid | HTTP 400 `invalid_args` | Use `0 < target_reliability < 1`; stay at or below a realistic host claim | -| Offer gone / not rentable | HTTP 404/410 `no_such_ask` | Re-search and rent a current offer ID | -| Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage, then rent again | +| Offer unavailable / stale | HTTP 404 `invalid_args` (check `msg` for `no_such_ask`) | Re-search and rent a current offer ID | +| Offer no longer exists | HTTP 410 `no_such_ask` | Re-search for a new offer ID | +| Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage (`allocated_storage` / `--storage`), then rent again | Hold `allocated_storage` / `--storage` constant when comparing `dph_total` across runs or between CLI and REST. @@ -237,7 +246,9 @@ Production settlement uses the multi-window reliability blend described above, n 2. Open **price details** (or the instance billing panel) and confirm an **SLA charge** line is present. 3. If the UI shows your **reliability target**, confirm it matches what you selected at search time. If you do not see a target or SLA charge, you likely rented without SLA coverage. -### API / CLI +### API integrators + +CLI can search with `target_reliability` but cannot enable or verify SLA on contracts today. Use the web console or REST for rent and post-rent verification. Console users: open **Instances** → select your instance → **price details** to confirm the SLA charge and target. Skip the block below if you do not use the API. diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index f93c8a60..f54d30d4 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -1,8 +1,6 @@ --- title: "Hosting Overview" -slug: "xP4AEPJl2F6woPGcD7EWl" -createdAt: "Tue Jan 14 2025 01:09:17 GMT+0000 (Coordinated Universal Time)" -updatedAt: "Fri Jul 11 2025 22:44:42 GMT+0000 (Coordinated Universal Time)" +description: "Set up hosting on Vast.ai: accounts, machines, offers, maintenance, and common questions." "canonical": "/host/hosting-overview" --- @@ -231,6 +229,8 @@ You can then look at your [instance tab](https://cloud.vast.ai/instances/) to ma ## Maintenance +**Prerequisite:** Planned maintenance during active SLA rentals requires the [Vast CLI](/cli/hello-world) or REST — there is no in-console scheduler. Install the CLI before you enable SLA — see [Before you enable SLA](/host/sla-offers#before-you-enable-sla). + Remember that a single machine may have multiple active rental contracts from different clients, each with its own rental end date. All rental contracts must be honored. Unlisting the offer prevents new rentals but does not end existing ones. If you have active contracts, you can set the offer end date to match the latest rental end date so new clients rent instances that end together. Once that date is reached, unlist and perform maintenance. From ef2815f6b49e9d803e203af38eb1bfde545ddf01 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Fri, 24 Jul 2026 14:23:06 -0700 Subject: [PATCH 24/45] docs(sla): address doc-review consensus (cycle 8) Document SLA create-instance error modes in OpenAPI and un-nest client Choose your path from the opt-in Note. Co-authored-by: Cursor --- api-reference/openapi.yaml | 19 ++++++++++++++++++- .../openapi/yaml/create_instance.yaml | 8 +++++++- guides/instances/choosing/sla-coverage.mdx | 4 ++-- 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index a589de1c..03c0eb8b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1662,6 +1662,14 @@ paths: Use the same value you used in search when comparing `dph_total`. + Common failures: `invalid_args` when the offer has no SLA or the + target is out of range; + + `invalid_price` when the quote is stale relative to search (re-search + with matching storage + + and `target_reliability`, then rent again). See [SLA Coverage](/guides/instances/choosing/sla-coverage). + ' runtype: type: string @@ -1807,7 +1815,16 @@ paths: description: ID of the newly created instance contract example: 1234568 '400': - description: Bad Request + description: 'Bad Request. Includes invalid or out-of-range `target_reliability`, + renting with SLA on a non-SLA + + offer, SSH key requirements, and `invalid_price` when the create request + does not match a fresh + + search quote (re-search with the same `target_reliability` and disk/storage, + then retry). + + ' content: application/json: schema: diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index 1306ca66..0324cf0d 100644 --- a/api-reference/openapi/yaml/create_instance.yaml +++ b/api-reference/openapi/yaml/create_instance.yaml @@ -72,6 +72,9 @@ paths: Client SLA coverage target (greater than 0 and less than 1). When set on an SLA-enabled offer (`sla_r_claim > 0`), locks SLA terms on the new contract. Omit or set to 0 for a non-SLA rental. Use the same value you used in search when comparing `dph_total`. + Common failures: `invalid_args` when the offer has no SLA or the target is out of range; + `invalid_price` when the quote is stale relative to search (re-search with matching storage + and `target_reliability`, then rent again). See [SLA Coverage](/guides/instances/choosing/sla-coverage). runtype: type: string description: | @@ -190,7 +193,10 @@ paths: description: ID of the newly created instance contract example: 1234568 '400': - description: Bad Request + description: | + Bad Request. Includes invalid or out-of-range `target_reliability`, renting with SLA on a non-SLA + offer, SSH key requirements, and `invalid_price` when the create request does not match a fresh + search quote (re-search with the same `target_reliability` and disk/storage, then retry). content: application/json: schema: diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 2d3507b7..26b8dcba 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -10,6 +10,7 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing **SLA is opt-in.** In the console, set a reliability target in Search before you rent. Via the **REST API**, pass `target_reliability` on **create-instance** (`PUT /api/v0/asks/{id}/`). Renting without a target means **no SLA charge and no SLA credits**, even on offers where the host has enabled SLA. + `target_reliability` is **not yet** available on the published `vastai create instance` CLI or Python SDK `create_instance()`. Searching with `target_reliability` only affects quoted pricing — it does **not** enable SLA on the contract unless you pass the same value at create-instance via **REST** or the **web console**. @@ -22,7 +23,6 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing | Rent with SLA in the console | [Finding SLA offers → In the web console](#in-the-web-console) | | Understand charges and credits | [How pricing works](#how-pricing-works) → [What happens after you rent](#what-happens-after-you-rent) | | Automate search → rent → verify | [API automation](#api-automation) (REST; CLI cannot rent with SLA yet) | - SLA applies to **on-demand rentals only** — not interruptible/bid or reserved/prepay contracts. See [Instance Pricing](/guides/instances/pricing). @@ -38,7 +38,7 @@ SLA is a **contractual, per-rental** reliability guarantee with automatic daily For SLA-covered on-demand contracts: -- You are charged for **compute and the SLA charge** for the rental day, including periods when the instance is unavailable. +- You are charged for **compute, storage, and the SLA charge** for the rental day, including periods when the instance is unavailable. - Offline time is tracked as an outage in reliability measurements. - If you qualify for compensation, a **settlement credit** posts after daily settlement (UTC) — typically within a few hours after UTC midnight for the prior day — not in the same hour as the outage. From 8144a1be6ae1a0a27bebeccc25ed3a8b6a7312fc Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:18:45 -0700 Subject: [PATCH 25/45] docs(sla): clarify hosts do not set beta; fix navbar FAQ URL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite sla_max_beta as an optional client-β cap and use an absolute FAQ href for Mintlify. Co-authored-by: Cursor --- api-reference/openapi.yaml | 16 ++++++++-------- api-reference/openapi/yaml/list_machine.yaml | 6 ++++-- api-reference/openapi/yaml/show_machines.yaml | 4 +++- docs.json | 2 +- host/sla-offers.mdx | 6 ++++-- 5 files changed, 20 insertions(+), 14 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 03c0eb8b..afb572da 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4608,13 +4608,11 @@ paths: sla_max_beta: type: number format: float - description: 'Optional term capping how path-dependent a client''s - timescale mix can be. - - Must be in (0, 1) and at least the default beta derived at your - claim. - - ' + description: "Optional ask term capping the client-derived timescale\ + \ mix (\u03B2) this offer accepts.\nHosts do not set \u03B2 \u2014\ + \ the platform derives \u03B2 from the client's target_reliability\ + \ at rent.\nLeave unset for uncapped. When set, must be in (0,\ + \ 1) and at least the default beta\nderived at your claim.\n" sla_r_target: type: number format: float @@ -9000,7 +8998,9 @@ paths: description: SLA confidence spread around the claim. sla_max_beta: type: number - description: Optional cap on client timescale mix (beta). + description: "Optional cap on the client-derived timescale\ + \ mix (\u03B2) this ask accepts.\nHosts do not set \u03B2\ + ; leave unset for uncapped.\n" example: machines: - id: '12345' diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index c23e8eed..5d41abcb 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -82,8 +82,10 @@ paths: type: number format: float description: | - Optional term capping how path-dependent a client's timescale mix can be. - Must be in (0, 1) and at least the default beta derived at your claim. + Optional ask term capping the client-derived timescale mix (β) this offer accepts. + Hosts do not set β — the platform derives β from the client's target_reliability at rent. + Leave unset for uncapped. When set, must be in (0, 1) and at least the default beta + derived at your claim. sla_r_target: type: number format: float diff --git a/api-reference/openapi/yaml/show_machines.yaml b/api-reference/openapi/yaml/show_machines.yaml index 761bd7a9..09d61837 100644 --- a/api-reference/openapi/yaml/show_machines.yaml +++ b/api-reference/openapi/yaml/show_machines.yaml @@ -56,7 +56,9 @@ paths: description: SLA confidence spread around the claim. sla_max_beta: type: number - description: Optional cap on client timescale mix (beta). + description: | + Optional cap on the client-derived timescale mix (β) this ask accepts. + Hosts do not set β; leave unset for uncapped. example: machines: - id: "12345" diff --git a/docs.json b/docs.json index 62713899..06c0f7e8 100644 --- a/docs.json +++ b/docs.json @@ -827,7 +827,7 @@ "links": [ { "label": "FAQ", - "href": "/guides/reference/faq" + "href": "https://docs.vast.ai/guides/reference/faq" }, { "label": "Discord", diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 34ce73e4..83c6a58f 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -106,7 +106,9 @@ When you list or update a machine, set SLA fields via the host console or `PUT / ### Advanced: `sla_max_beta` (optional) -Omit unless Vast support directs you. Optional ask term `sla_max_beta` limits how path-dependent a client's timescale mix can be for long-running contracts. Must be in `(0, 1)` and at least the default β derived at your claim. Most hosts should leave it unset. +Hosts do **not** set β (timescale mix). The platform derives β from the client's `target_reliability` at rent time. + +`sla_max_beta` is an optional ask **term**: a ceiling on how high a client-derived β this offer will accept (it caps collateral-lock duration for long-running contracts). Leave it unset for an uncapped offer. If you set it, it must be in `(0, 1)` and at least the default β derived at your claim — otherwise listing is rejected. Omit unless Vast support directs you. **`sla_r_target` is not host-settable.** If you send `sla_r_target` or legacy `sla_reliability` on `create_asks/`, they are **ignored**. Clients supply their coverage target at search/rent time (`target_reliability`). Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x` — they use different scales. Use the mapping table on the [backtester page](/host/sla-backtester#confidence-values-p). @@ -151,7 +153,7 @@ Offers with invalid combinations are rejected at listing time: - `sla_r_claim` must be `0` (disable) or greater than 0 and at most **0.9999**. Exactly `1.0` is rejected. - When claim is positive, `sla_sigma_x` must be positive and at most `3.0` (defaults to `0.5` if omitted). -- Optional `sla_max_beta` must be in `(0, 1)` and at least the default β derived at your claim. +- Optional `sla_max_beta` must be in `(0, 1)` and at least the default β derived at your claim. Hosts do not set β; this field only caps the client-derived β the offer accepts. Omit for uncapped. If listing is rejected with `error: "invalid_sla_params"`, check the `msg` field against the rules above. Other SLA listing errors include `sla_not_approved` and `sla_daemon_outdated`. From ced2a11d305e6e6498f299ceaf35cc1c829c5da2 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:24:27 -0700 Subject: [PATCH 26/45] docs(sla): address doc-review consensus (cycle 1) Fix stale end_date examples, elevate CLI search-vs-rent SLA warnings, and soften sla_max_beta wording. Co-authored-by: Cursor --- api-reference/openapi.yaml | 15 ++++++------ api-reference/openapi/yaml/list_machine.yaml | 8 +++---- api-reference/openapi/yaml/show_machines.yaml | 4 ++-- cli/reference/search-offers.mdx | 5 ++++ guides/instances/choosing/sla-coverage.mdx | 6 ++++- host/hosting-overview.mdx | 10 +++++++- host/sla-offers.mdx | 24 +++++++++++-------- snippets/host/cli/list-machine.mdx | 8 +++---- snippets/host/cli/schedule-maint.mdx | 4 ++-- snippets/host/sdk/list-machine.mdx | 4 +++- 10 files changed, 56 insertions(+), 32 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index afb572da..f97b8ccf 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4608,11 +4608,12 @@ paths: sla_max_beta: type: number format: float - description: "Optional ask term capping the client-derived timescale\ - \ mix (\u03B2) this offer accepts.\nHosts do not set \u03B2 \u2014\ - \ the platform derives \u03B2 from the client's target_reliability\ - \ at rent.\nLeave unset for uncapped. When set, must be in (0,\ - \ 1) and at least the default beta\nderived at your claim.\n" + description: "Optional ask term capping how aggressively long-running\ + \ contracts may weight recent\nuptime versus longer history in\ + \ settlement. Hosts do not set \u03B2 \u2014 the platform derives\n\ + \u03B2 from the client's target_reliability at rent. Leave unset\ + \ for uncapped. When set,\nmust be in (0, 1) and at least the\ + \ default beta derived at your claim.\n" sla_r_target: type: number format: float @@ -8998,8 +8999,8 @@ paths: description: SLA confidence spread around the claim. sla_max_beta: type: number - description: "Optional cap on the client-derived timescale\ - \ mix (\u03B2) this ask accepts.\nHosts do not set \u03B2\ + description: "Optional cap on client-derived \u03B2 for\ + \ this ask (support-directed). Hosts do not\nset \u03B2\ ; leave unset for uncapped.\n" example: machines: diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index 5d41abcb..52d59d7d 100644 --- a/api-reference/openapi/yaml/list_machine.yaml +++ b/api-reference/openapi/yaml/list_machine.yaml @@ -82,10 +82,10 @@ paths: type: number format: float description: | - Optional ask term capping the client-derived timescale mix (β) this offer accepts. - Hosts do not set β — the platform derives β from the client's target_reliability at rent. - Leave unset for uncapped. When set, must be in (0, 1) and at least the default beta - derived at your claim. + Optional ask term capping how aggressively long-running contracts may weight recent + uptime versus longer history in settlement. Hosts do not set β — the platform derives + β from the client's target_reliability at rent. Leave unset for uncapped. When set, + must be in (0, 1) and at least the default beta derived at your claim. sla_r_target: type: number format: float diff --git a/api-reference/openapi/yaml/show_machines.yaml b/api-reference/openapi/yaml/show_machines.yaml index 09d61837..d0d56e5e 100644 --- a/api-reference/openapi/yaml/show_machines.yaml +++ b/api-reference/openapi/yaml/show_machines.yaml @@ -57,8 +57,8 @@ paths: sla_max_beta: type: number description: | - Optional cap on the client-derived timescale mix (β) this ask accepts. - Hosts do not set β; leave unset for uncapped. + Optional cap on client-derived β for this ask (support-directed). Hosts do not + set β; leave unset for uncapped. example: machines: - id: "12345" diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index d048b8ae..832deade 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -87,6 +87,11 @@ vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=Fal # vastai create instance does not support SLA yet. # Always set --storage explicitly (CLI default 5 GiB; REST search default 8 GB) when comparing dph_total. vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --storage 50 --order dph_total +``` + + +**Next step:** Search pricing does not enable SLA. To rent with coverage, use the web console or REST create-instance — see [SLA Coverage → API automation](/guides/instances/choosing/sla-coverage#api-automation). `vastai create instance` does not support SLA yet. + # datacenter GPUs with minimum compute capability and TFLOPs vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True' diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 26b8dcba..d15caeb0 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -56,7 +56,7 @@ total ≈ GPU + storage + bandwidth + SLA charge | --- | --- | | Your reliability target | Higher target → higher SLA charge | | Host SLA claim | Maximum reliability the host advertises on the listing (`expected_reliability`). Higher claim → lower SLA charge at a given target | -| Host confidence | Host-side pricing setting that affects SLA charge size. **Not shown on offer cards** — compare offers using `dph_total` or the SLA charge line in the price breakdown | +| Host confidence | Host-side pricing setting that affects SLA charge size. **You do not set this** — the host chooses it, and it is **not shown on offer cards**. Compare offers using `dph_total` or the SLA charge line in the price breakdown | **Rule of thumb:** pick a target **at or below** the host's claim for the best value. Asking for 99% coverage on a host who only claims 95% costs much more than asking for 95% on a host who claims 99%. @@ -72,6 +72,10 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 ## Finding SLA offers + +**CLI-only renters:** You can search and price SLA offers from the CLI (`target_reliability` in `vastai search offers`), but SLA coverage is enabled only at create-instance time via the **web console** or **REST API** (`target_reliability` on `PUT /api/v0/asks/{id}/`). `vastai create instance` does not support SLA yet. See [API automation](#api-automation). + + ### In the web console 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index f54d30d4..72acffdc 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -5,6 +5,10 @@ description: "Set up hosting on Vast.ai: accounts, machines, offers, maintenance --- + +**Looking to rent GPUs?** See [Finding & Renting Instances](/guides/instances/choosing/find-and-rent) and [SLA Coverage](/guides/instances/choosing/sla-coverage). + + Vast is a GPU marketplace. Hosts sell GPU resources on the marketplace. Hosts are responsible for: - Setup: installing Ubuntu, creating disk partitions, installing NVIDIA drivers, opening network ports on the router and installing the Vast hosting software. @@ -36,7 +40,7 @@ Clients have high expectations coming from AWS or GCP. As a host, plan to offer ## Offers and Rental Contracts -Hosts can create offers (sometimes called listings) through the CLI command `list machine` or the GUI on the [host machines page](https://cloud.vast.ai/host/machines). +Hosts can create offers (sometimes called listings) through the CLI command `list machine` or the GUI on the [host machines page](https://cloud.vast.ai/host/machines). SLA claim and confidence require **Set Pricing → SLA** in the console or REST `create_asks/` — not `vastai list machine` today (see [SLA Offers](/host/sla-offers)). The main offer parameters include: @@ -225,6 +229,10 @@ vastai create instance --image pytorch/pytorch:latest --jupyter --direct -- Use `./vastai` instead of `vastai` when running from the install directory. + +CLI self-tests create **non-SLA** rentals (`vastai create instance` does not accept `target_reliability`). To test SLA contract terms on your own offer, use the console with a reliability target or REST create-instance with `target_reliability` — see [SLA Coverage](/guides/instances/choosing/sla-coverage). + + You can then look at your [instance tab](https://cloud.vast.ai/instances/) to make sure that pytorch loaded correctly along with jupyter and ssh. Click on the \<\_ button to get the ssh command to connect to the instance. Test the direct ssh command. Click on the open button to test jupyter. If the button is stuck "connecting" then there is most likely a problem with the port configuration on the router in front of the machine. Once finished, destroy the instance. ## Maintenance diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 83c6a58f..16fb9b84 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -106,9 +106,9 @@ When you list or update a machine, set SLA fields via the host console or `PUT / ### Advanced: `sla_max_beta` (optional) -Hosts do **not** set β (timescale mix). The platform derives β from the client's `target_reliability` at rent time. +**Support-only — omit unless Vast support directs you.** Hosts do **not** set β (timescale mix). The platform derives β from the client's `target_reliability` at rent time. -`sla_max_beta` is an optional ask **term**: a ceiling on how high a client-derived β this offer will accept (it caps collateral-lock duration for long-running contracts). Leave it unset for an uncapped offer. If you set it, it must be in `(0, 1)` and at least the default β derived at your claim — otherwise listing is rejected. Omit unless Vast support directs you. +`sla_max_beta` is an optional ask term that caps how aggressively long-running contracts may weight recent uptime versus longer history in settlement. Leave it unset for an uncapped offer. If you set it, it must be in `(0, 1)` and at least the default β derived at your claim — otherwise listing is rejected. **`sla_r_target` is not host-settable.** If you send `sla_r_target` or legacy `sla_reliability` on `create_asks/`, they are **ignored**. Clients supply their coverage target at search/rent time (`target_reliability`). Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x` — they use different scales. Use the mapping table on the [backtester page](/host/sla-backtester#confidence-values-p). @@ -139,11 +139,13 @@ Do not assume the dashboard score equals SLA reliability. Before choosing `sla_r **This only changes how SLA charges are priced — it does not change how reliability is measured or what credit you owe when a client's target is missed.** Prefer the console controls. Set raw `sla_sigma_x` via the API when automating. -| Guidance | Pricing effect | `sla_sigma_x` | Risk if you miss claim | +| Console label | API `sla_sigma_x` | Backtester `p` | Pricing effect | | --- | --- | --- | --- | -| Tight | Lowest client SLA charges at a given target | `0.2` | Highest charge sensitivity | -| Normal (default) | Balanced | `0.5` | Moderate | -| Wide | Highest client SLA charges at a given target | `1.0` | Lowest charge sensitivity | +| Tight | `0.2` | ~0.83 | Lowest client SLA charges at a given target | +| Normal (default) | `0.5` | ~0.6667 | Balanced | +| Wide | `1.0` | ~0.50 | Highest client SLA charges at a given target | + +**Never copy backtester `p` into `sla_sigma_x` — the scales are inverted.** See the full mapping on the [backtester page](/host/sla-backtester#confidence-values-p). Higher confidence (tighter spread) → lower client SLA charges, but less room for reliability to slip before settlement credits grow. @@ -231,11 +233,11 @@ curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ "price_gpu": 3.50, "sla_r_claim": 0.99, "sla_sigma_x": 0.5, - "end_date": 1735689600 + "end_date": 1893456000 }' ``` -Set `end_date` so the offer does not stay open indefinitely — especially important for SLA commitments. See [Offer End Date](/host/hosting-overview#offer-end-date). Convert a calendar date to Unix seconds: `date -u -d '2025-01-01' +%s` (Linux) or `date -u -j -f '%Y-%m-%d' '2025-01-01' +%s` (macOS). The CLI also accepts `MM/DD/YYYY` via `-e`. +Replace `end_date` with a **future** Unix timestamp — past dates expire the offer immediately (example `1893456000` = 2030-01-01 00:00 UTC). Set `end_date` so the offer does not stay open indefinitely — especially important for SLA commitments. See [Offer End Date](/host/hosting-overview#offer-end-date). Convert a calendar date to Unix seconds: `date -u -d '2030-01-01' +%s` (Linux) or `date -u -j -f '%Y-%m-%d' '2030-01-01' +%s` (macOS). The CLI also accepts `MM/DD/YYYY` via `-e`. Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). @@ -245,7 +247,7 @@ Minimal example: { "machine": 12345, "price_gpu": 3.50, - "end_date": 1735689600, + "end_date": 1893456000, "sla_r_claim": 0.99, "sla_sigma_x": 0.5 } @@ -267,7 +269,9 @@ Machine `id` may be a string in raw JSON. The response is wrapped in a `machines Then `PUT /api/v0/machines/create_asks/` with merged fields. -### Fleet listing workflow +### Fleet listing workflow (advanced — fleet operators only) + +Validate `price_gpu`, `end_date`, and `min_chunk` before each PUT. Prefer reading existing SLA fields from each machine rather than hardcoding claim/confidence. Skip unlisted machines. For multiple machines, loop sequentially — do not parallelize without backoff: diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index d935e4ad..36bd93b5 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -69,15 +69,15 @@ vastai list machine ID [options] ## Description Performs the same action as pressing the "LIST" button on the site https://cloud.vast.ai/host/machines. -On the end date the listing will expire and your machine will unlist. However, any existing rental contracts will still remain until ended by their owners. +On the end date, the listing will expire and your machine will unlist. However, any existing rental contracts will still remain until ended by their owners. Once you list your machine and it is rented, it is extremely important that you don't interfere with the machine in any way. -If your machine has an active rental contract and then goes offline, crashes, or has performance problems, this could permanently lower your reliability rating. -We strongly recommend you test the machine first and only list when ready. +If your machine has an active rental contract and then goes offline, crashes, or has performance problems, this can lower your marketplace reliability score (it recovers with continued good uptime — see [Hosting overview](/host/hosting-overview#why-did-the-reliability-on-my-machine-decrease)). +We strongly recommend you test the machine first and only list when ready. Always set an offer end date (`-e`) for SLA listings — see [Offer End Date](/host/hosting-overview#offer-end-date) and [SLA Offers](/host/sla-offers). ## Examples ```bash -vastai list machine +vastai list machine -g 3.50 -e "01/01/2030" ``` ## Global Options diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index e3f28613..8b0f2858 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -8,12 +8,12 @@ Schedule an upcoming maintenance window vastai schedule maint id [--sdate START_DATE --duration DURATION --maintenance_category MAINTENANCE_CATEGORY] ``` -`schedule maintenance` is an alias for `schedule maint` if your CLI build supports both spellings. Prefer `maint`. +`schedule maintenance` is an alias for `schedule maint` if your CLI build supports both spellings. Prefer `maint`. Requires `machine_write` on scoped API keys — see [Permissions](/api-reference/permissions). ## Arguments - id of machine to schedule maintenance for + ID of the machine to schedule maintenance for. ## Options diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 5258f72d..e1143f00 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -67,6 +67,8 @@ VastAI.list_machine( from vastai import VastAI client = VastAI(api_key="YOUR_API_KEY") -result = client.list_machine(id=12345, price_gpu=3.50) +# Base listing only — for SLA, use the console or REST create_asks after list_machine() +# see SLA Offers → API (for automation): /host/sla-offers#api-for-automation +result = client.list_machine(id=12345, price_gpu=3.50, end_date="01/01/2030") print(result) ``` From 4988232252b23c44b9f6536f1e13b7b873c39b2a Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:29:03 -0700 Subject: [PATCH 27/45] docs(sla): address doc-review consensus (cycle 2) Repair search-offers examples fence, split backtester 400 error rows, and name show-instances verify path. Co-authored-by: Cursor --- cli/reference/search-offers.mdx | 9 ++++----- guides/instances/choosing/sla-coverage.mdx | 2 +- host/sla-backtester.mdx | 5 ++++- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 832deade..ccb8ed5d 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -87,11 +87,6 @@ vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=Fal # vastai create instance does not support SLA yet. # Always set --storage explicitly (CLI default 5 GiB; REST search default 8 GB) when comparing dph_total. vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --storage 50 --order dph_total -``` - - -**Next step:** Search pricing does not enable SLA. To rent with coverage, use the web console or REST create-instance — see [SLA Coverage → API automation](/guides/instances/choosing/sla-coverage#api-automation). `vastai create instance` does not support SLA yet. - # datacenter GPUs with minimum compute capability and TFLOPs vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True' @@ -112,6 +107,10 @@ vastai search offers 'reliability > 0.99 num_gpus>=4 verified=False rented=any' vastai search offers 'cpu_arch=arm64' ``` + +**Next step:** Search pricing does not enable SLA. To rent with coverage, use the web console or REST create-instance — see [SLA Coverage → API automation](/guides/instances/choosing/sla-coverage#api-automation). `vastai create instance` does not support SLA yet. + + ## Available Fields | Field | Type | Description | diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index d15caeb0..8133d2f5 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -170,7 +170,7 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe **API key permissions:** create a scoped key with `misc` (search/bundles), `instance_write` (create-instance), and preferably `instance_read` (verify show-instances). See [Authentication](/api-reference/authentication) and [Permissions](/api-reference/permissions). -**3. Verify** via show-instances: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. +**3. Verify** via `GET /api/v1/instances/` (show-instances / `vastai show instances`): confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. | Symptom | Typical response | What to do | | --- | --- | --- | diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 6ddcc8c1..3d495b85 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -264,7 +264,10 @@ Higher confidence (higher `p`) → tighter spread → lower SLA charges for clie | HTTP | `error` / shape | Cause | | --- | --- | --- | -| 400 | `invalid_range`, `range_too_large`, `bad_request`, `invalid_params` | Invalid query parameters or simulation failure | +| 400 | `invalid_range` | Date window invalid | +| 400 | `range_too_large` | Window exceeds the maximum span | +| 400 | `bad_request` | Out-of-range `r`, `p`, or date parameters | +| 400 | `invalid_params` | Simulation math failure after validation (check claim/confidence inputs) | | 403 | `not_owner` | Machine belongs to another host | | 404 | `machine_not_found` | Invalid `machine_id` | | 429 | *(rate limited)* | Too many requests — retry with backoff. See [Rate Limits and Errors](/api-reference/rate-limits-and-errors). | From 176654abcb8040c94ec1c4307ba9164b59af75a2 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:33:34 -0700 Subject: [PATCH 28/45] docs(sla): address doc-review consensus (cycle 3) Resolve CLI verify contradiction, document instances pagination and search order/limit for SLA automation. Co-authored-by: Cursor --- cli/reference/search-offers.mdx | 2 +- guides/instances/choosing/sla-coverage.mdx | 5 +++-- host/hosting-overview.mdx | 8 +++++++- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index ccb8ed5d..b850613a 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -48,7 +48,7 @@ vastai search offers [--help] [--api-key API_KEY] [--raw] - + Maximum number of offers to return. Prefer an explicit limit when comparing SLA-inclusive `dph_total` results; combine with `--order` / `-o` as needed. diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 8133d2f5..09c92b3a 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -147,6 +147,7 @@ curl -s -X POST "https://console.vast.ai/api/v0/bundles/" \ "limit": 20, "type": "ondemand", "allocated_storage": 50, + "order": [["dph_total", "asc"]], "target_reliability": {"eq": 0.95}, "has_sla": {"eq": true}, "expected_reliability": {"gte": 0.99} @@ -170,7 +171,7 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe **API key permissions:** create a scoped key with `misc` (search/bundles), `instance_write` (create-instance), and preferably `instance_read` (verify show-instances). See [Authentication](/api-reference/authentication) and [Permissions](/api-reference/permissions). -**3. Verify** via `GET /api/v1/instances/` (show-instances / `vastai show instances`): confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. +**3. Verify** via `GET /api/v1/instances/` or `vastai show instances --raw`: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. `GET /api/v1/instances/` returns at most 25 instances per request — paginate with `next_token` until exhausted if you manage many rentals. | Symptom | Typical response | What to do | | --- | --- | --- | @@ -252,7 +253,7 @@ Production settlement uses the multi-window reliability blend described above, n ### API integrators -CLI can search with `target_reliability` but cannot enable or verify SLA on contracts today. Use the web console or REST for rent and post-rent verification. +CLI can search with `target_reliability` and can **read** post-rent SLA fields via `vastai show instances --raw`, but cannot **enable** SLA at create-instance time (`vastai create instance` has no `target_reliability`). Use the web console or REST to rent with SLA. Console users: open **Instances** → select your instance → **price details** to confirm the SLA charge and target. Skip the block below if you do not use the API. diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index 72acffdc..cd74edb3 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -230,7 +230,13 @@ vastai create instance --image pytorch/pytorch:latest --jupyter --direct -- Use `./vastai` instead of `vastai` when running from the install directory. -CLI self-tests create **non-SLA** rentals (`vastai create instance` does not accept `target_reliability`). To test SLA contract terms on your own offer, use the console with a reliability target or REST create-instance with `target_reliability` — see [SLA Coverage](/guides/instances/choosing/sla-coverage). +CLI self-tests create **non-SLA** rentals (`vastai create instance` does not accept `target_reliability`). To test SLA contract terms on your own offer: + +1. Create a separate client account (see above), or use REST from that account. +2. In the console Search filters, set a **Reliability target**, rent your own offer, and confirm an **SLA charge** line before continuing — or `PUT /api/v0/asks/{id}/` with `target_reliability`. +3. Destroy the test instance when done. + +See [SLA Coverage](/guides/instances/choosing/sla-coverage) for renter-side details. You can then look at your [instance tab](https://cloud.vast.ai/instances/) to make sure that pytorch loaded correctly along with jupyter and ssh. Click on the \<\_ button to get the ssh command to connect to the instance. Test the direct ssh command. Click on the open button to test jupyter. If the button is stuck "connecting" then there is most likely a problem with the port configuration on the router in front of the machine. Once finished, destroy the instance. From 1f721358f01bb8173cc17a1ee391dce3de269867 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:33:39 -0700 Subject: [PATCH 29/45] docs(sla): fix weigh wording in sla_max_beta Co-authored-by: Cursor --- host/sla-offers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 16fb9b84..26f4a59f 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -108,7 +108,7 @@ When you list or update a machine, set SLA fields via the host console or `PUT / **Support-only — omit unless Vast support directs you.** Hosts do **not** set β (timescale mix). The platform derives β from the client's `target_reliability` at rent time. -`sla_max_beta` is an optional ask term that caps how aggressively long-running contracts may weight recent uptime versus longer history in settlement. Leave it unset for an uncapped offer. If you set it, it must be in `(0, 1)` and at least the default β derived at your claim — otherwise listing is rejected. +`sla_max_beta` is an optional ask term that caps how aggressively long-running contracts may weigh recent uptime versus longer history in settlement. Leave it unset for an uncapped offer. If you set it, it must be in `(0, 1)` and at least the default β derived at your claim — otherwise listing is rejected. **`sla_r_target` is not host-settable.** If you send `sla_r_target` or legacy `sla_reliability` on `create_asks/`, they are **ignored**. Clients supply their coverage target at search/rent time (`target_reliability`). Do **not** copy numeric `p` values from the SLA Backtester into `sla_sigma_x` — they use different scales. Use the mapping table on the [backtester page](/host/sla-backtester#confidence-values-p). From 14c06b97a592183ac0ae40b5d460be7ff7f5535d Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:39:58 -0700 Subject: [PATCH 30/45] docs(sla): address doc-review consensus (cycle 4) Fix maint scheduling examples, dph_total/bandwidth wording, after_token pagination, and CLI rent decision rule. Co-authored-by: Cursor --- cli/reference/search-offers.mdx | 11 +++----- guides/instances/choosing/find-and-rent.mdx | 4 +-- guides/instances/choosing/sla-coverage.mdx | 31 +++++++++------------ host/sla-offers.mdx | 11 +++++--- snippets/host/cli/list-machine.mdx | 4 +-- snippets/host/cli/schedule-maint.mdx | 8 ++++-- snippets/host/sdk/list-machine.mdx | 4 +-- 7 files changed, 33 insertions(+), 40 deletions(-) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index b850613a..b002255a 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -81,11 +81,8 @@ bool = True | False # reliable single RTX 3090, no conflicts with stopped instances vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False' -# SLA offers: host claim ≥ 99%, your coverage target 95% (see SLA Coverage) -# Search pricing only — target_reliability here quotes dph_total; it does not enable SLA on rent. -# To cover a rental: console Search target, or REST create-instance with target_reliability. -# vastai create instance does not support SLA yet. -# Always set --storage explicitly (CLI default 5 GiB; REST search default 8 GB) when comparing dph_total. +# SLA search quote (enable coverage at rent via console/REST — see SLA Coverage) +# Always set --storage explicitly when comparing dph_total (CLI default 5 GiB ≠ REST 8 GB). vastai search offers 'has_sla=true expected_reliability>=0.99 target_reliability=0.95' --storage 50 --order dph_total # datacenter GPUs with minimum compute capability and TFLOPs @@ -108,7 +105,7 @@ vastai search offers 'cpu_arch=arm64' ``` -**Next step:** Search pricing does not enable SLA. To rent with coverage, use the web console or REST create-instance — see [SLA Coverage → API automation](/guides/instances/choosing/sla-coverage#api-automation). `vastai create instance` does not support SLA yet. +**Next step:** Search quotes SLA pricing only — see [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers) to rent with coverage (console or REST). ## Available Fields @@ -159,7 +156,7 @@ vastai search offers 'cpu_arch=arm64' | `reliability` | float | machine reliability score (see FAQ for explanation) | | `expected_reliability` | float | host’s advertised SLA reliability claim on the offer | | `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | -| `target_reliability` | float | your desired SLA coverage level (greater than 0 and less than 1); drives SLA charge in `dph_total` for **search quotes only**. Pass the same value at create-instance via console or REST to enable coverage — `vastai create instance` does not support SLA yet (see [SLA Coverage](/guides/instances/choosing/sla-coverage)) | +| `target_reliability` | float | desired SLA coverage (0–1 exclusive); prices `dph_total` in search only — see [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers) to enable at rent | | `rentable` | bool | is the instance currently rentable | | `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances | | `storage_cost` | float | storage cost in $/GB/month | diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index edd5f264..399ca3e1 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -58,13 +58,13 @@ All stats shown are the portion of the total machine rented. - Max Duration: The maximum length of a rental contract on this machine - Reliability Score: A measure of the machine's historical uptime and health. All machines start at 60%. This is **not** the host SLA claim. - Rental Option: RENT button -- **SLA (optional):** Available on **on-demand** rentals only. Set a **reliability target** in Search before clicking **RENT** to opt in — see [SLA Coverage](/guides/instances/choosing/sla-coverage). +- **SLA (optional):** Available on **on-demand** rentals only. Set a **reliability target** in Search, then confirm the price breakdown includes an **SLA charge** line before clicking **RENT** — see [SLA Coverage](/guides/instances/choosing/sla-coverage). ## Instance Disk Size The storage slider is both a search filter and a parameter input which determines the storage allocation size - it's important to size this correctly before creating any instance. -When the instance is created, the disk size is set and cannot be modified. It is important to estimate how much disk you will need and then to move the slider to the desired disk size. The default disk size for an instance is 10GB. Use the slider to allocate more or less, taking into consideration that providers charge for disk allocation even when the instance is stopped. +When the instance is created, the disk size is set and cannot be modified. It is important to estimate how much disk you will need and then to move the slider to the desired disk size. The default disk size for an instance is 10GB. Use the slider to allocate more or less, taking into consideration that providers charge for disk allocation even when the instance is stopped. When comparing `dph_total` across the console, CLI, and REST search, hold storage constant — defaults differ (console 10 GB, REST search 8 GB, CLI `--storage` 5 GiB); see [SLA Coverage](/guides/instances/choosing/sla-coverage#api-automation). ![Diskspace](https://vast.ai/uploads/Search/DiskSpace.png) diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 09c92b3a..516ea4a2 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -13,7 +13,7 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing -`target_reliability` is **not yet** available on the published `vastai create instance` CLI or Python SDK `create_instance()`. Searching with `target_reliability` only affects quoted pricing — it does **not** enable SLA on the contract unless you pass the same value at create-instance via **REST** or the **web console**. +`target_reliability` is **not yet** available on the published `vastai create instance` CLI or Python SDK `create_instance()`. Searching with a target only quotes pricing — use the **web console** or **REST** create-instance to enable coverage (see [Finding SLA offers](#finding-sla-offers)). ## Choose your path @@ -46,12 +46,14 @@ SLA is most useful for **long-running production workloads** where unexpected do ## How pricing works -Total hourly cost with SLA (`dph_total` = all-in dollars per hour in search): +Quoted hourly cost with SLA in search (`dph_total`): ``` -total ≈ GPU + storage + bandwidth + SLA charge +dph_total ≈ GPU + storage + SLA charge ``` +Bandwidth is billed separately from usage (`inet_*` rates) and is **not** included in `dph_total`. + | Factor | What it means for you | | --- | --- | | Your reliability target | Higher target → higher SLA charge | @@ -67,14 +69,13 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 | Cost component | Approx. rate | | --- | --- | | GPU compute | $3.50/hr | +| Storage (at search allocation) | ~$0.01/hr | | SLA charge | ~$0.008/hr | -| **Total (`dph_total`)** | ~$3.51/hr | +| **Total (`dph_total`)** | ~$3.52/hr | ## Finding SLA offers - -**CLI-only renters:** You can search and price SLA offers from the CLI (`target_reliability` in `vastai search offers`), but SLA coverage is enabled only at create-instance time via the **web console** or **REST API** (`target_reliability` on `PUT /api/v0/asks/{id}/`). `vastai create instance` does not support SLA yet. See [API automation](#api-automation). - +**Decision rule:** Search filters **quote** SLA pricing only. Coverage activates only when you rent via the **web console** (Reliability target set) or **REST** create-instance (`target_reliability` on `PUT /api/v0/asks/{id}/`). The CLI cannot enable SLA at rent time today — see [API automation](#api-automation) for the minimum REST rent path. ### In the web console @@ -129,15 +130,11 @@ When you search with an SLA target, reserved-instance discounts may not apply to | A | $3.50 | 99% | 95% | ~$0.008 | | B | $3.50 | 95% | 95% | much higher | -Always compare **`dph_total`**, not just GPU price, when SLA matters. Search ranking also accounts for SLA cost. +Always compare **`dph_total`**, not just GPU price, when SLA matters. Sort by `dph_total` to compare total quoted cost. ### API automation - -SLA coverage is locked at **create-instance** time via `target_reliability` on `PUT /api/v0/asks/{id}/` (REST). Searching with a target only prices offers. The published CLI/SDK create-instance path does **not** accept `target_reliability` yet — use REST or the console to rent with SLA. - - -**1. Search** (prices `dph_total` at your target — include storage explicitly; REST defaults to 8 GB, CLI `--storage` defaults to 5 GiB): +**1. Search** (prices `dph_total` at your target — include storage explicitly so quotes are comparable): ```bash curl -s -X POST "https://console.vast.ai/api/v0/bundles/" \ @@ -171,7 +168,7 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe **API key permissions:** create a scoped key with `misc` (search/bundles), `instance_write` (create-instance), and preferably `instance_read` (verify show-instances). See [Authentication](/api-reference/authentication) and [Permissions](/api-reference/permissions). -**3. Verify** via `GET /api/v1/instances/` or `vastai show instances --raw`: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. `GET /api/v1/instances/` returns at most 25 instances per request — paginate with `next_token` until exhausted if you manage many rentals. +**3. Verify** via `GET /api/v1/instances/` or `vastai show instances --raw`: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. `GET /api/v1/instances/` returns at most 25 instances per request — paginate by passing each response’s `next_token` as the **`after_token`** query parameter until `next_token` is null. | Symptom | Typical response | What to do | | --- | --- | --- | @@ -181,7 +178,7 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe | Offer no longer exists | HTTP 410 `no_such_ask` | Re-search for a new offer ID | | Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage (`allocated_storage` / `--storage`), then rent again | -Hold `allocated_storage` / `--storage` constant when comparing `dph_total` across runs or between CLI and REST. +Hold storage constant when comparing `dph_total`: console Instance Disk Size defaults to **10 GB**, REST search `allocated_storage` defaults to **8 GB**, and CLI `--storage` defaults to **5 GiB**. Mismatched defaults make the same offer look differently priced across tools. ## What happens after you rent @@ -253,9 +250,7 @@ Production settlement uses the multi-window reliability blend described above, n ### API integrators -CLI can search with `target_reliability` and can **read** post-rent SLA fields via `vastai show instances --raw`, but cannot **enable** SLA at create-instance time (`vastai create instance` has no `target_reliability`). Use the web console or REST to rent with SLA. - -Console users: open **Instances** → select your instance → **price details** to confirm the SLA charge and target. Skip the block below if you do not use the API. +Console users: open **Instances** → select your instance → **price details** to confirm the SLA charge and target. Skip the block below if you do not use the API. (CLI can **read** these fields via `vastai show instances --raw`; enabling SLA still requires console or REST — see [Finding SLA offers](#finding-sla-offers).)
API integrators: field names and filters diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 26f4a59f..e9869fcf 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -73,7 +73,7 @@ Think of an SLA offer as two host ideas plus one client choice: When a client rents an on-demand instance on your SLA-listed offer with a chosen target: -- They pay **compute** (GPU, storage, bandwidth) plus a **small hourly SLA charge** included in `dph_total`. +- While a rental runs they pay GPU, storage, bandwidth (usage-based), and a **small hourly SLA charge**. In search results, **`dph_total`** is the quoted hourly rental cost: GPU + storage + SLA charge at the quoted allocation — **not** bandwidth. - Each UTC calendar day, Vast measures reliability for the contract and settles the SLA. - **Strong reliability relative to the client's target** → you keep the SLA charge for that day. - **Shortfalls** → credits flow to the client from your earnings (bounded by that day's covered compute). @@ -441,9 +441,12 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi **CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC. **CLI `--duration` is in hours.** ```bash -# Example: 2026-08-01 02:00:00 UTC → epoch seconds -# Linux: date -u -d '2026-08-01 02:00:00' +%s -vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 --maintenance_category software +# Planned window: 2026-08-01 02:00:00 UTC (≥24 hours ahead when you run this) +# Prefer computing the epoch so the comment and value stay in sync: +vastai schedule maint MACHINE_ID \ + --sdate "$(date -u -d '2026-08-01 02:00:00' +%s)" \ + --duration 2 \ + --maintenance_category software ``` REST equivalent: `PUT /api/v0/machines/{machine_id}/dnotify` with `"sdate": "2026-08-01T02:00:00Z"` (optional `"maintenance_reason": "OS kernel upgrade"`) — see [Schedule Maintenance](/api-reference/machines/schedule-maint). diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 36bd93b5..2e29ac5b 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -3,9 +3,7 @@ Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. -SLA parameters (`--sla_r_claim`, `--sla_sigma_x`) are **not yet available** in the published CLI. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation) and [List Machine](/api-reference/machines/list-machine). - -Volume and duration options (`-v`, `-z`, `-l`) are available in the CLI today. +SLA listing flags are **not yet** in the published CLI — use console **Set Pricing → SLA** or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration options (`-v`, `-z`, `-l`) work in the CLI today. ## Usage diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 8b0f2858..adbb25cb 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -45,9 +45,11 @@ The same `schedule maint` command is used for both **planned** and **emergency** If SLA is enabled and you need planned downtime during an active rental, schedule at least 24 hours in advance. See [SLA Offers → Scheduled maintenance](/host/sla-offers#scheduled-maintenance). ```bash -# Replace MACHINE_ID; set --sdate to a future UTC epoch (≥24h ahead for planned credit review) -# Linux: date -u -d '2026-08-01 02:00:00' +%s -vastai schedule maint MACHINE_ID --sdate 1785549600 --duration 2 --maintenance_category software +# Replace MACHINE_ID; --sdate must be a future UTC epoch (≥24h ahead for planned credit review) +vastai schedule maint MACHINE_ID \ + --sdate "$(date -u -d '2026-08-01 02:00:00' +%s)" \ + --duration 2 \ + --maintenance_category software ``` ### Emergency or unplanned maintenance diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index e1143f00..961e996e 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -3,9 +3,7 @@ Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. -SLA parameters (`sla_r_claim`, `sla_sigma_x`) are **not yet available** in the published Python SDK. Use **Set Pricing → SLA** in the host console, or `PUT /api/v0/machines/create_asks/` via REST — see [SLA Offers](/host/sla-offers#api-for-automation). - -Volume and duration listing parameters (`vol_size`, `vol_price`, `duration`, `price_min_bid`) require the CLI or REST API today — they are not in the SDK signature below. +SLA listing parameters are **not yet** in the published Python SDK — use console **Set Pricing → SLA** or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing params require CLI or REST today. ## Signature From 67136eb71e48c2e72f0ab1e2173cec6f02147dcb Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:44:48 -0700 Subject: [PATCH 31/45] docs(sla): address doc-review consensus (cycle 5) Align create-instance 410/storage notes and correct SDK volume/duration tooling scope. Co-authored-by: Cursor --- cli/reference/search-offers.mdx | 4 ++++ guides/instances/choosing/sla-coverage.mdx | 6 +++--- snippets/host/sdk/list-machine.mdx | 2 +- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index b002255a..8fe467d7 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -77,6 +77,10 @@ bool = True | False ## Examples + +**Search quotes SLA pricing only.** `vastai create instance` cannot pass `target_reliability` today — use the web console or REST to enable coverage; see [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers). + + ```bash # reliable single RTX 3090, no conflicts with stopped instances vastai search offers 'reliability > 0.98 num_gpus=1 gpu_name=RTX_3090 rented=False' diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 516ea4a2..aff79d46 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -175,16 +175,16 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe | Target on a non-SLA offer | HTTP 400 `invalid_args` | Search with `has_sla=true`; confirm `expected_reliability` | | Target out of range / invalid | HTTP 400 `invalid_args` | Use `0 < target_reliability < 1`; stay at or below a realistic host claim | | Offer unavailable / stale | HTTP 404 `invalid_args` (check `msg` for `no_such_ask`) | Re-search and rent a current offer ID | -| Offer no longer exists | HTTP 410 `no_such_ask` | Re-search for a new offer ID | +| Cannot start immediately (`cancel_unavail`) | HTTP 410 `no_such_ask` | Offer cannot start now; pick another offer or retry later — see [Create Instance](/api-reference/instances/create-instance) | | Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage (`allocated_storage` / `--storage`), then rent again | -Hold storage constant when comparing `dph_total`: console Instance Disk Size defaults to **10 GB**, REST search `allocated_storage` defaults to **8 GB**, and CLI `--storage` defaults to **5 GiB**. Mismatched defaults make the same offer look differently priced across tools. +Hold storage constant when comparing `dph_total` and when chaining search → rent: console Instance Disk Size defaults to **10 GB**, REST search `allocated_storage` defaults to **8 GB**, and CLI `--storage` defaults to **5 GiB**. REST create-instance requires `disk` ≥ **8 GB**, so a CLI search at the 5 GiB default can quote a price you cannot rent via REST without raising storage — use ≥ 8 GB (or the same explicit value) for CLI search → REST rent flows. CLI `--storage` is in GiB; REST `allocated_storage` / create `disk` are in GB. ## What happens after you rent When you rent an SLA-backed offer **with a target set**: -1. **Contract terms lock in** — your reliability target, the host's claim, and confidence are fixed for that rental. +1. **Contract terms lock in** — your reliability target, the host's claim, and host confidence (how the host priced SLA around their claim) are fixed for that rental. You only compare the SLA charge or `dph_total` — confidence is a host-side pricing knob, not a setting you control. 2. **Daily billing** — you pay compute plus the SLA charge each day. 3. **Daily settlement** — Vast measures reliability across multiple timescales and calculates any SLA credit. 4. **Credits appear in billing** — settlement credits improve your balance; strong days mean you paid the SLA charge with no credit. diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 961e996e..7797f163 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. -SLA listing parameters are **not yet** in the published Python SDK — use console **Set Pricing → SLA** or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing params require CLI or REST today. +SLA listing parameters are **not yet** in the published Python SDK — use console **Set Pricing → SLA** or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing options (`-v`, `-z`, `-l`) are available in the **CLI** today; they are not documented on the REST `list_machine` / `create_asks` body. ## Signature From 2ecade5587fcd35ff9f7c058c83c2dfe9f23abc4 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:50:53 -0700 Subject: [PATCH 32/45] docs(sla): address doc-review consensus (cycle 6) Correct search offer id labeling, console disk sizing path, and REST search parity filters. Co-authored-by: Cursor --- cli/reference/search-offers.mdx | 2 +- guides/instances/choosing/find-and-rent.mdx | 6 ++++-- guides/instances/choosing/sla-coverage.mdx | 4 ++++ host/sla-offers.mdx | 2 +- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 8fe467d7..68c2b1de 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -146,7 +146,7 @@ vastai search offers 'cpu_arch=arm64' | `gpu_frac` | float | ratio of GPUs in the offer to GPUs in the system | | `gpu_display_active` | bool | True if the GPU has a display attached | | `has_avx` | bool | CPU supports AVX instruction set | -| `id` | int | instance unique ID | +| `id` | int | Offer/ask ID. Use this value when renting via create-instance (`PUT /api/v0/asks/{id}/`) | | `inet_down` | float | internet download speed in Mb/s | | `inet_down_cost` | float | internet download bandwidth cost in $/GB | | `inet_up` | float | internet upload speed in Mb/s | diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index 399ca3e1..1af4c3c7 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -62,9 +62,11 @@ All stats shown are the portion of the total machine rented. ## Instance Disk Size -The storage slider is both a search filter and a parameter input which determines the storage allocation size - it's important to size this correctly before creating any instance. +The storage slider is both a search filter and a parameter input which determines the storage allocation size — size it correctly before you create an instance. -When the instance is created, the disk size is set and cannot be modified. It is important to estimate how much disk you will need and then to move the slider to the desired disk size. The default disk size for an instance is 10GB. Use the slider to allocate more or less, taking into consideration that providers charge for disk allocation even when the instance is stopped. When comparing `dph_total` across the console, CLI, and REST search, hold storage constant — defaults differ (console 10 GB, REST search 8 GB, CLI `--storage` 5 GiB); see [SLA Coverage](/guides/instances/choosing/sla-coverage#api-automation). +When the instance is created, the disk size is set and cannot be modified. Estimate how much disk you need, then move the slider to that size. The default disk size in the console is 10GB. Hosts charge for disk allocation even when the instance is stopped. + +If you compare prices across the console, CLI, and REST, match disk size first — defaults differ by channel. See [SLA Coverage → API automation](/guides/instances/choosing/sla-coverage#api-automation). ![Diskspace](https://vast.ai/uploads/Search/DiskSpace.png) diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index aff79d46..e49edbfd 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -134,6 +134,8 @@ Always compare **`dph_total`**, not just GPU price, when SLA matters. Sort by `d ### API automation +Console-only renters can skip this section — use [In the web console](#in-the-web-console) above. + **1. Search** (prices `dph_total` at your target — include storage explicitly so quotes are comparable): ```bash @@ -143,6 +145,8 @@ curl -s -X POST "https://console.vast.ai/api/v0/bundles/" \ -d '{ "limit": 20, "type": "ondemand", + "verified": {"eq": true}, + "rentable": {"eq": true}, "allocated_storage": 50, "order": [["dph_total", "asc"]], "target_reliability": {"eq": 0.95}, diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index e9869fcf..e0fc952c 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -147,7 +147,7 @@ Do not assume the dashboard score equals SLA reliability. Before choosing `sla_r **Never copy backtester `p` into `sla_sigma_x` — the scales are inverted.** See the full mapping on the [backtester page](/host/sla-backtester#confidence-values-p). -Higher confidence (tighter spread) → lower client SLA charges, but less room for reliability to slip before settlement credits grow. +**Tighter confidence** (tighter spread; console label **Tight**) → lower client SLA charges and less settlement exposure for the host. **Wider confidence** (console label **Wide**) → higher client SLA charges and more exposure on bad days. ### Validation rules From e4ce0873c3619e1c8c32675fc0b9e989d5890a36 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 08:55:33 -0700 Subject: [PATCH 33/45] docs(sla): address doc-review consensus (cycle 7) Align outage billing wording, confidence vs credit risk, and search target_reliability bounds. Co-authored-by: Cursor --- api-reference/openapi.yaml | 12 ++++++------ api-reference/openapi/yaml/search_offers.yaml | 6 ++++-- guides/instances/choosing/sla-coverage.mdx | 7 ++++--- host/sla-backtester.mdx | 2 +- host/sla-offers.mdx | 4 ++-- 5 files changed, 17 insertions(+), 14 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index f97b8ccf..99a35c35 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -6660,12 +6660,12 @@ paths: host SLA claim. Example: {"gte": 0.99}' target_reliability: type: object - description: 'Client SLA coverage target (0-1). When set, search - prices include the SLA charge in dph_total - - and returns search.slaPremiumPerHour. Example: {"eq": 0.95} - - ' + description: "Client SLA coverage target. Value must be greater\ + \ than 0 and less than 1 (exclusive bounds \u2014\nsame as create-instance).\ + \ When set, search prices include the SLA charge in dph_total\ + \ and\nreturns search.slaPremiumPerHour. Pass the same target\ + \ again on PUT /api/v0/asks/{id}/ to\nenable coverage. Example:\ + \ {\"eq\": 0.95}\n" has_sla: type: object description: 'Restrict to offers with SLA enabled (true) or without diff --git a/api-reference/openapi/yaml/search_offers.yaml b/api-reference/openapi/yaml/search_offers.yaml index b93c497b..ea2b6f91 100644 --- a/api-reference/openapi/yaml/search_offers.yaml +++ b/api-reference/openapi/yaml/search_offers.yaml @@ -92,8 +92,10 @@ paths: target_reliability: type: object description: | - Client SLA coverage target (0-1). When set, search prices include the SLA charge in dph_total - and returns search.slaPremiumPerHour. Example: {"eq": 0.95} + Client SLA coverage target. Value must be greater than 0 and less than 1 (exclusive bounds — + same as create-instance). When set, search prices include the SLA charge in dph_total and + returns search.slaPremiumPerHour. Pass the same target again on PUT /api/v0/asks/{id}/ to + enable coverage. Example: {"eq": 0.95} has_sla: type: object description: | diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index e49edbfd..89ea609f 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -21,15 +21,16 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing | Goal | Start here | | --- | --- | | Rent with SLA in the console | [Finding SLA offers → In the web console](#in-the-web-console) | +| I use only the CLI today | Search can **quote** SLA pricing; enable coverage via console or [API automation](#api-automation) (REST) — `vastai create instance` cannot pass `target_reliability` yet | | Understand charges and credits | [How pricing works](#how-pricing-works) → [What happens after you rent](#what-happens-after-you-rent) | -| Automate search → rent → verify | [API automation](#api-automation) (REST; CLI cannot rent with SLA yet) | +| Automate search → rent → verify | [API automation](#api-automation) (REST) | SLA applies to **on-demand rentals only** — not interruptible/bid or reserved/prepay contracts. See [Instance Pricing](/guides/instances/pricing). -You do not post escrow or collateral for SLA. You pay the SLA charge while the instance runs. Settlement happens automatically on a daily cadence. +You do not post escrow or collateral for SLA. You pay the SLA charge while your rental contract is active (including during outages, before settlement credits are applied). Settlement happens automatically on a daily UTC cadence. ## What SLA protects @@ -81,7 +82,7 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). 2. In Search filters (left filter bar), set **Reliability target** to your desired coverage level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. -3. Optionally narrow to host SLA listings with an SLA-enabled / `has_sla` filter if shown. That filter only restricts which offers appear — it does **not** replace setting **Reliability target**. If you do not see a separate SLA toggle, set Reliability target and confirm the SLA charge line before rent. +3. Optionally narrow to host SLA listings with an SLA-enabled / `has_sla` filter if shown. **Filtering to SLA-enabled offers is not the same as enabling coverage** — you must still set **Reliability target** and confirm the SLA charge line before you rent. If you do not see a separate SLA toggle, set Reliability target and confirm the SLA charge line before rent. 4. Before you click **RENT**, confirm the price breakdown shows an **SLA charge** line. No SLA charge means no SLA coverage for that rental. 5. Rent as usual. Your target is locked at rent time. diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index 3d495b85..ae094624 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -258,7 +258,7 @@ The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. The mappin | `0.6667` | Normal (default) | `sla_sigma_x ≈ 0.5` | | `0.50` | Wide | `sla_sigma_x ≈ 1.0` | -Higher confidence (higher `p`) → tighter spread → lower SLA charges for clients at a given target, but less room for reliability to slip before credits grow. +Higher confidence (higher `p`) → tighter spread → lower simulated SLA charges for clients at a given target (more competitive `dph_total`). Tighter `p` does **not** reduce credit owed on a miss — use `worst_day_loss` and `reliability=` overrides to model settlement exposure. ## Error responses diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index e0fc952c..4fc75b52 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -73,7 +73,7 @@ Think of an SLA offer as two host ideas plus one client choice: When a client rents an on-demand instance on your SLA-listed offer with a chosen target: -- While a rental runs they pay GPU, storage, bandwidth (usage-based), and a **small hourly SLA charge**. In search results, **`dph_total`** is the quoted hourly rental cost: GPU + storage + SLA charge at the quoted allocation — **not** bandwidth. +- While a rental **contract** is active, clients pay GPU, storage, bandwidth (usage-based), and a **small hourly SLA charge** — including during downtime. Settlement credits for missed targets are calculated separately at UTC day boundaries. In search results, **`dph_total`** is the quoted hourly rental cost: GPU + storage + SLA charge at the quoted allocation — **not** bandwidth. - Each UTC calendar day, Vast measures reliability for the contract and settles the SLA. - **Strong reliability relative to the client's target** → you keep the SLA charge for that day. - **Shortfalls** → credits flow to the client from your earnings (bounded by that day's covered compute). @@ -147,7 +147,7 @@ Do not assume the dashboard score equals SLA reliability. Before choosing `sla_r **Never copy backtester `p` into `sla_sigma_x` — the scales are inverted.** See the full mapping on the [backtester page](/host/sla-backtester#confidence-values-p). -**Tighter confidence** (tighter spread; console label **Tight**) → lower client SLA charges and less settlement exposure for the host. **Wider confidence** (console label **Wide**) → higher client SLA charges and more exposure on bad days. +**Tighter confidence** (tighter spread; console label **Tight**) → lower client SLA charges (more competitive `dph_total`). **Wider confidence** (console label **Wide**) → higher client SLA charges. Confidence does **not** change the credit formula when a target is missed — use `worst_day_loss` and stress-test with the backtester `reliability=` override for tail-risk planning. ### Validation rules From d5a4706f915e0756171fe8e4ee6a2acd42225686 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:01:37 -0700 Subject: [PATCH 34/45] docs(sla): address doc-review consensus (cycle 8) Harden fleet listing example, add cancel/reschedule maintenance, and clarify daemon preflight. Co-authored-by: Cursor --- guides/instances/choosing/sla-coverage.mdx | 2 +- host/sla-offers.mdx | 42 +++++++++++++++++----- snippets/host/cli/schedule-maint.mdx | 2 ++ 3 files changed, 37 insertions(+), 9 deletions(-) diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 89ea609f..378869ad 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -82,7 +82,7 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 1. Open [Search](https://cloud.vast.ai/create/) and confirm **On-demand** is selected (SLA does not apply to interruptible rentals). 2. In Search filters (left filter bar), set **Reliability target** to your desired coverage level — for example **95%** or **99%**. If you do not set a target, you are not opting into SLA. -3. Optionally narrow to host SLA listings with an SLA-enabled / `has_sla` filter if shown. **Filtering to SLA-enabled offers is not the same as enabling coverage** — you must still set **Reliability target** and confirm the SLA charge line before you rent. If you do not see a separate SLA toggle, set Reliability target and confirm the SLA charge line before rent. +3. Optionally narrow results with an SLA-enabled / `has_sla` filter if shown. Filtering listings is **not** the same as enabling coverage. 4. Before you click **RENT**, confirm the price breakdown shows an **SLA charge** line. No SLA charge means no SLA coverage for that rental. 5. Rent as usual. Your target is locked at rent time. diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 4fc75b52..92ef32c3 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -271,22 +271,45 @@ Then `PUT /api/v0/machines/create_asks/` with merged fields. ### Fleet listing workflow (advanced — fleet operators only) -Validate `price_gpu`, `end_date`, and `min_chunk` before each PUT. Prefer reading existing SLA fields from each machine rather than hardcoding claim/confidence. Skip unlisted machines. +`PUT /api/v0/machines/create_asks/` publishes a live listing (same as **LIST**). Only run this loop on machines you intend to list or update. Validate `price_gpu`, `end_date`, and `min_chunk` before each PUT. Prefer reading existing SLA fields from each machine rather than hardcoding claim/confidence. Skip incomplete machines. + +**Before fleet SLA rollout:** + +1. Update host daemons fleet-wide per the [host setup guide](https://cloud.vast.ai/host/setup/). +2. On **Host → Machines**, confirm each machine is healthy (no red error status) and retry **LIST** / `create_asks` after the daemon reconnects. +3. If listing still returns `sla_daemon_outdated` after an update, contact support with the machine ID — there is no documented `show machines` daemon-version field for a preflight `jq` filter today. For multiple machines, loop sequentially — do not parallelize without backoff: -1. `PUT /api/v0/machines/create_asks/` with `machine` plus SLA fields and required base pricing. -2. On `429`, sleep and retry with exponential backoff. -3. On `invalid_sla_params`, `sla_not_approved`, `sla_daemon_outdated`, or `machine_locked`, log the machine ID and continue or abort per your rollout policy. +1. Skip machines missing base pricing fields. +2. `PUT /api/v0/machines/create_asks/` with `machine` plus SLA fields (preserve existing claim/confidence when set). +3. On `429`, sleep and retry with exponential backoff. +4. On `invalid_sla_params`, `sla_not_approved`, `sla_daemon_outdated`, or `machine_locked`, log the machine ID and continue or abort per your rollout policy. See [Fleet workflow](/host/sla-backtester#fleet-workflow) in the backtester for a similar sequential pattern. ```bash export VAST_API_KEY="YOUR_API_KEY" +# Set DRY_RUN=0 to apply; default prints payloads only +DRY_RUN="${DRY_RUN:-1}" machines=$(vastai show machines --raw) for id in $(vastai show machines -q); do - body=$(echo "$machines" | jq -c --arg id "$id" \ - '.machines[] | select((.id|tostring) == $id) | {machine: (.id|tonumber), price_gpu, end_date, min_chunk, sla_r_claim: 0.99, sla_sigma_x: 0.5}') + machine=$(echo "$machines" | jq -c --arg id "$id" \ + '.machines[] | select((.id|tostring) == $id)') + price=$(echo "$machine" | jq -r '.price_gpu // empty') + end=$(echo "$machine" | jq -r '.end_date // empty') + chunk=$(echo "$machine" | jq -r '.min_chunk // empty') + if [ -z "$price" ] || [ -z "$end" ] || [ -z "$chunk" ]; then + echo "skip $id: missing price_gpu/end_date/min_chunk"; continue + fi + # Preserve per-machine SLA tuning; defaults apply only when unset + body=$(echo "$machine" | jq -c \ + '{machine: (.id|tonumber), price_gpu, end_date, min_chunk, + sla_r_claim: (.sla_r_claim // 0.99), + sla_sigma_x: (.sla_sigma_x // 0.5)}') + if [ "$DRY_RUN" != "0" ]; then + echo "dry-run machine_id=$id payload: $body"; continue + fi resp=$(curl -s -X PUT "https://console.vast.ai/api/v0/machines/create_asks/" \ -H "Authorization: Bearer $VAST_API_KEY" \ -H "Content-Type: application/json" \ @@ -296,7 +319,7 @@ for id in $(vastai show machines -q); do done ``` -Fetch the fleet once before the loop — do not call `show machines --raw` inside the loop. On fleets of 20+ machines, expect several minutes; back off on HTTP 429. +Fetch the fleet once before the loop — do not call `show machines --raw` inside the loop. On fleets of 20+ machines, expect several minutes; back off on HTTP 429. Tune claim/confidence per machine (backtester + earnings) before setting `DRY_RUN=0`. **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -451,6 +474,8 @@ vastai schedule maint MACHINE_ID \ REST equivalent: `PUT /api/v0/machines/{machine_id}/dnotify` with `"sdate": "2026-08-01T02:00:00Z"` (optional `"maintenance_reason": "OS kernel upgrade"`) — see [Schedule Maintenance](/api-reference/machines/schedule-maint). +**Cancel or reschedule:** To cancel a window, use [`vastai cancel maint`](/host/cli/cancel-maint) (requires `machine_write`) or the [REST cancel-maintenance API](/api-reference/machines/cancel-maint). To reschedule, cancel the existing window, then run `schedule maint` with a new `--sdate` (still ≥24 hours ahead for planned SLA maintenance). + **Emergency or unplanned downtime:** Notify clients if possible using `schedule maint`, but expect **full SLA settlement exposure**. Advance-notice credits do not apply to unplanned outages. See [CLI install](/cli/hello-world) if you have not set up the CLI. @@ -466,7 +491,8 @@ Use the [SLA Earnings Backtester](/host/sla-backtester) (API-only; requires a `m ## When things go wrong - **Listing rejected (`invalid_sla_params`)** — Re-check claim and `sla_sigma_x` against [validation rules](#validation-rules). -- **`sla_not_approved` / `sla_daemon_outdated`** — Contact support or update the daemon from the host setup page. +- **`sla_not_approved`** — Contact support; you can keep a non-SLA listing while approval is pending. +- **`sla_daemon_outdated`** — Update the host daemon from the [host setup guide](https://cloud.vast.ai/host/setup/), confirm the machine reconnects on **Host → Machines**, then retry LIST / `create_asks`. If the error persists, contact support with the machine ID. - **Unexpected credit** — Review reliability; re-run the backtester with a low `reliability` stress value (for example `0.01`). - **Severe outage** — Disable SLA on new contracts: open **Host → Machines** → **Set Pricing → SLA**, set claim to `0` (or use API `sla_r_claim=0`); contact [Discord](https://discord.gg/hSuEbSQ4X8) before relisting. diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index adbb25cb..31b66a36 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -60,6 +60,8 @@ If the machine must go offline without adequate notice, still run `schedule main vastai schedule maint MACHINE_ID --sdate "$(date -u +%s)" --duration 1 --maintenance_category power ``` +To cancel a scheduled window, use [`vastai cancel maint`](/host/cli/cancel-maint). To reschedule, cancel first, then schedule a new window (≥24 hours ahead for planned SLA credit review). + ## Examples ```bash From daec3586e3acf94217b2a394e93073c257b1fcc1 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:18:20 -0700 Subject: [PATCH 35/45] docs(sla): address doc-review consensus (cycle 9) Stop fleet script from inventing SLA claims; document maint rate limits; trim duplicate tooling warnings. Co-authored-by: Cursor --- cli/reference/search-offers.mdx | 6 +----- host/sla-offers.mdx | 20 +++++++++++++------- snippets/host/cli/list-machine.mdx | 2 +- snippets/host/cli/schedule-maint.mdx | 2 +- snippets/host/sdk/list-machine.mdx | 2 +- 5 files changed, 17 insertions(+), 15 deletions(-) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 68c2b1de..fa3d277f 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -96,7 +96,7 @@ vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True' vastai search offers 'reliability>0.99 num_gpus=4 geolocation in [TW,SE]' # reliable RTX 3090 or 4090 NOT in China or Vietnam -vastai search offers 'reliability>0.99 gpu_name in ["RTX 4090", "RTX 3090"] geolocation notin [CN,VN]' +vastai search offers 'reliability>0.99 gpu_name in [RTX_4090, RTX_3090] geolocation notin [CN,VN]' # nvidia driver 535.86.05 or greater with various constraints vastai search offers 'disk_space>146 duration>24 gpu_ram>10 cuda_vers>=12.1 direct_port_count>=2 driver_version >= 535.86.05' @@ -108,10 +108,6 @@ vastai search offers 'reliability > 0.99 num_gpus>=4 verified=False rented=any' vastai search offers 'cpu_arch=arm64' ``` - -**Next step:** Search quotes SLA pricing only — see [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers) to rent with coverage (console or REST). - - ## Available Fields | Field | Type | Description | diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 92ef32c3..0c5686ee 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -209,7 +209,7 @@ In the host console, open **Host Machines** → select your machine → **Set Pr New hosts: use the web console steps above first. Use the API when you need scripting, partial updates, or fleet automation. -SLA listing via `vastai list machine` and `VastAI.list_machine()` is **not yet available** in the published CLI/SDK. Use the REST API below until tooling support is released. +SLA listing via CLI/SDK is not available yet — use the REST API below (or console **Set Pricing → SLA**). See also [List Machine](/api-reference/machines/list-machine) for the same `create_asks` body. #### Before you start @@ -241,7 +241,11 @@ Replace `end_date` with a **future** Unix timestamp — past dates expire the of Open-ended offers (no `end_date`) combined with SLA expose you to indefinite asymmetric payout risk. See [Offer End Date](/host/hosting-overview#offer-end-date). -Minimal example: + +Do not use the JSON below alone for a **first** listing. First-time `create_asks` requests must also include `min_chunk` and typical disk/bandwidth pricing — see [Hosting overview](/host/hosting-overview#offers-and-rental-contracts). Use this as an **SLA-fields** reference when base pricing is already configured. + + +SLA fields example (existing listing): ```json { @@ -302,11 +306,13 @@ for id in $(vastai show machines -q); do if [ -z "$price" ] || [ -z "$end" ] || [ -z "$chunk" ]; then echo "skip $id: missing price_gpu/end_date/min_chunk"; continue fi - # Preserve per-machine SLA tuning; defaults apply only when unset + # Opt-in only: skip machines with no positive SLA claim (do not invent 0.99) + if ! echo "$machine" | jq -e '(.sla_r_claim // 0) > 0' >/dev/null; then + echo "skip $id: no positive sla_r_claim (enable SLA per machine first)"; continue + fi body=$(echo "$machine" | jq -c \ '{machine: (.id|tonumber), price_gpu, end_date, min_chunk, - sla_r_claim: (.sla_r_claim // 0.99), - sla_sigma_x: (.sla_sigma_x // 0.5)}') + sla_r_claim, sla_sigma_x: (.sla_sigma_x // 0.5)}') if [ "$DRY_RUN" != "0" ]; then echo "dry-run machine_id=$id payload: $body"; continue fi @@ -319,7 +325,7 @@ for id in $(vastai show machines -q); do done ``` -Fetch the fleet once before the loop — do not call `show machines --raw` inside the loop. On fleets of 20+ machines, expect several minutes; back off on HTTP 429. Tune claim/confidence per machine (backtester + earnings) before setting `DRY_RUN=0`. +Fetch the fleet once before the loop — do not call `show machines --raw` inside the loop. On fleets of 20+ machines, expect several minutes; back off on HTTP 429. Configure claim/confidence per machine (console or single-machine `create_asks`) before running with `DRY_RUN=0` — the loop only updates machines that already have a positive `sla_r_claim`. **SLA-only update** — include `machine` plus SLA fields; omit unrelated offer fields you intend to keep: @@ -461,7 +467,7 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi **Planned SLA maintenance (may earn credit):** Schedule at least 24 hours in advance with [`vastai schedule maint`](/host/cli/schedule-maint) (or the [REST schedule-maintenance API](/api-reference/machines/schedule-maint)). Include `--sdate` and `--duration`. Advance notice (not the category value) is what makes maintenance “planned” for SLA credit review. Valid `--maintenance_category` values: `power`, `internet`, `disk`, `gpu`, `software`, `other`. Credit eligibility is evaluated on a case-by-case basis. -**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC. **CLI `--duration` is in hours.** +**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC. **CLI `--duration` is in hours.** Schedule maintenance **sequentially** across a fleet — the API is rate-limited (~2.5 requests/second). On HTTP 429, wait and retry with backoff (for example, `sleep 2` between machines). ```bash # Planned window: 2026-08-01 02:00:00 UTC (≥24 hours ahead when you run this) diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 2e29ac5b..342620c6 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. -SLA listing flags are **not yet** in the published CLI — use console **Set Pricing → SLA** or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration options (`-v`, `-z`, `-l`) work in the CLI today. +SLA listing flags are not in the published CLI yet — see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration options (`-v`, `-z`, `-l`) work today. ## Usage diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 31b66a36..432a4d2a 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -60,7 +60,7 @@ If the machine must go offline without adequate notice, still run `schedule main vastai schedule maint MACHINE_ID --sdate "$(date -u +%s)" --duration 1 --maintenance_category power ``` -To cancel a scheduled window, use [`vastai cancel maint`](/host/cli/cancel-maint). To reschedule, cancel first, then schedule a new window (≥24 hours ahead for planned SLA credit review). +To cancel a scheduled window, use [`vastai cancel maint`](/host/cli/cancel-maint). To reschedule, cancel first, then schedule a new window (≥24 hours ahead for planned SLA credit review). Across many machines, schedule sequentially and back off on HTTP 429 (~2.5 req/s). ## Examples diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 7797f163..341376ae 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. -SLA listing parameters are **not yet** in the published Python SDK — use console **Set Pricing → SLA** or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing options (`-v`, `-z`, `-l`) are available in the **CLI** today; they are not documented on the REST `list_machine` / `create_asks` body. +SLA listing parameters are not in the published Python SDK yet — see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing options are CLI-only today. ## Signature From 56a33fcefbb4d519b7c6f4e584646f80e9acba8e Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:24:34 -0700 Subject: [PATCH 36/45] docs(sla): address doc-review consensus (cycle 10) Clarify cross-channel storage defaults and mark create-instance SLA as REST-only in OpenAPI. Co-authored-by: Cursor --- api-reference/openapi.yaml | 38 ++++++++----------- .../openapi/yaml/create_instance.yaml | 4 +- guides/instances/choosing/sla-coverage.mdx | 10 ++++- 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 99a35c35..3af10b99 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1579,29 +1579,21 @@ paths: /api/v0/asks/{id}: put: summary: create instance - description: 'Creates a new instance by accepting an "ask" contract from a provider. - - - - Use the search offers endpoint to discover available machines. - - - If `template_id` is provided, those template defaults are either merged - or overridden by parameters specified in the request body. - - - **Template Precedence Rules:** - - - **Scalar fields** (image, disk, runtype, etc.): Request value overrides - template value - - - **`env`**: Merged by key. Request values win on key conflicts - - - **`extra_filters`**: Merged by key. Request values win on key conflicts - - - For detailed template usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api). - - - CLI Usage: `vastai create instance [options]`' + description: "Creates a new instance by accepting an \"ask\" contract from a\ + \ provider.\n\n- Use the search offers endpoint to discover available machines.\n\ + - If `template_id` is provided, those template defaults are either merged\ + \ or overridden by parameters specified in the request body.\n\n**Template\ + \ Precedence Rules:**\n- **Scalar fields** (image, disk, runtype, etc.): Request\ + \ value overrides template value\n- **`env`**: Merged by key. Request values\ + \ win on key conflicts\n- **`extra_filters`**: Merged by key. Request values\ + \ win on key conflicts\n\nFor detailed template usage, see [Creating and Using\ + \ Templates with API](/api-reference/creating-and-using-templates-with-api).\n\ + \n**SLA note:** `target_reliability` is REST-only at rent time. The published\ + \ CLI and SDK cannot pass this field until support ships. Use the web console\ + \ or `PUT /api/v0/asks/{id}/` with `target_reliability` in the request body\ + \ to enable SLA coverage \u2014 see [SLA Coverage](/guides/instances/choosing/sla-coverage).\n\ + \nCLI Usage: `vastai create instance [options]` (no `target_reliability`\ + \ flag today)" security: - BearerAuth: [] tags: diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index 0324cf0d..d5627f18 100644 --- a/api-reference/openapi/yaml/create_instance.yaml +++ b/api-reference/openapi/yaml/create_instance.yaml @@ -23,7 +23,9 @@ paths: For detailed template usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api). - CLI Usage: `vastai create instance [options]` + **SLA note:** `target_reliability` is REST-only at rent time. The published CLI and SDK cannot pass this field until support ships. Use the web console or `PUT /api/v0/asks/{id}/` with `target_reliability` in the request body to enable SLA coverage — see [SLA Coverage](/guides/instances/choosing/sla-coverage). + + CLI Usage: `vastai create instance [options]` (no `target_reliability` flag today) security: - BearerAuth: [] tags: diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 378869ad..ab2c4c5a 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -21,7 +21,7 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing | Goal | Start here | | --- | --- | | Rent with SLA in the console | [Finding SLA offers → In the web console](#in-the-web-console) | -| I use only the CLI today | Search can **quote** SLA pricing; enable coverage via console or [API automation](#api-automation) (REST) — `vastai create instance` cannot pass `target_reliability` yet | +| I use only the CLI today | **Cannot enable SLA at rent time** — CLI search only quotes pricing. After rent, verify with `vastai show instances --raw` (`target_reliability` > 0). To enable coverage, use the console or [API automation](#api-automation) (REST) | | Understand charges and credits | [How pricing works](#how-pricing-works) → [What happens after you rent](#what-happens-after-you-rent) | | Automate search → rent → verify | [API automation](#api-automation) (REST) | @@ -183,7 +183,13 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe | Cannot start immediately (`cancel_unavail`) | HTTP 410 `no_such_ask` | Offer cannot start now; pick another offer or retry later — see [Create Instance](/api-reference/instances/create-instance) | | Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage (`allocated_storage` / `--storage`), then rent again | -Hold storage constant when comparing `dph_total` and when chaining search → rent: console Instance Disk Size defaults to **10 GB**, REST search `allocated_storage` defaults to **8 GB**, and CLI `--storage` defaults to **5 GiB**. REST create-instance requires `disk` ≥ **8 GB**, so a CLI search at the 5 GiB default can quote a price you cannot rent via REST without raising storage — use ≥ 8 GB (or the same explicit value) for CLI search → REST rent flows. CLI `--storage` is in GiB; REST `allocated_storage` / create `disk` are in GB. +| Channel | Default storage | Field | Units | +| --- | --- | --- | --- | +| Console | 10 GB | Instance disk size (UI) | GB | +| REST search (`POST /api/v0/bundles/`) | 8 GB | `allocated_storage` | GB | +| CLI (`vastai search offers`) | 5 GiB | `--storage` | GiB | + +**Rule:** Set the same explicit storage in search and create-instance. REST create-instance `disk` must be ≥ **8 GB** when you pass it (omit uses platform defaults — do not assume the CLI search default of 5 is rentable via REST). Pass matching numeric values across channels when chaining CLI search → REST rent (CLI help labels GiB; REST fields are labeled GB). ## What happens after you rent From 1601ecd3b5f717de8069570f4e4b69ae66ed7073 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:29:25 -0700 Subject: [PATCH 37/45] docs(sla): address doc-review consensus (cycle 11) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify GiB/GB search→rent integers, console-only SLA credits, and create-instance SLA gaps. Co-authored-by: Cursor --- cli/reference/create-instance.mdx | 4 ++++ guides/instances/choosing/find-and-rent.mdx | 2 +- guides/instances/choosing/sla-coverage.mdx | 12 +++++++++--- sdk/python/reference/create-instance.mdx | 4 ++++ 4 files changed, 18 insertions(+), 4 deletions(-) diff --git a/cli/reference/create-instance.mdx b/cli/reference/create-instance.mdx index faf04d2b..00b3bea5 100644 --- a/cli/reference/create-instance.mdx +++ b/cli/reference/create-instance.mdx @@ -5,6 +5,10 @@ sidebarTitle: "create instance" Create a new instance + +**SLA coverage:** `target_reliability` is not available on this CLI command. Searching with a reliability target only quotes pricing — use the web console or REST create-instance to enable SLA. See [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers). + + ## Usage ```bash diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index 1af4c3c7..f56dcd5e 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -58,7 +58,7 @@ All stats shown are the portion of the total machine rented. - Max Duration: The maximum length of a rental contract on this machine - Reliability Score: A measure of the machine's historical uptime and health. All machines start at 60%. This is **not** the host SLA claim. - Rental Option: RENT button -- **SLA (optional):** Available on **on-demand** rentals only. Set a **reliability target** in Search, then confirm the price breakdown includes an **SLA charge** line before clicking **RENT** — see [SLA Coverage](/guides/instances/choosing/sla-coverage). +- **SLA (optional):** Available on **on-demand** rentals only. Set a **reliability target** in Search, then confirm the price breakdown includes an **SLA charge** line before clicking **RENT**. Host SLA claim (`expected_reliability`) does not protect you unless you opt in — see [SLA Coverage](/guides/instances/choosing/sla-coverage). ## Instance Disk Size diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index ab2c4c5a..b0ac6330 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -76,6 +76,10 @@ Searching with **target reliability 95%** on an offer where the host **claims 99 ## Finding SLA offers + +**No SLA charge line in the price breakdown = no SLA coverage.** Filtering to SLA listings or searching with a reliability target only quotes pricing. Coverage requires setting **Reliability target** in the console (or passing `target_reliability` on REST create-instance) before you rent. + + **Decision rule:** Search filters **quote** SLA pricing only. Coverage activates only when you rent via the **web console** (Reliability target set) or **REST** create-instance (`target_reliability` on `PUT /api/v0/asks/{id}/`). The CLI cannot enable SLA at rent time today — see [API automation](#api-automation) for the minimum REST rent path. ### In the web console @@ -183,13 +187,13 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe | Cannot start immediately (`cancel_unavail`) | HTTP 410 `no_such_ask` | Offer cannot start now; pick another offer or retry later — see [Create Instance](/api-reference/instances/create-instance) | | Price mismatch after stale quote | HTTP 400 `invalid_price` | Re-search with the same `target_reliability` and storage (`allocated_storage` / `--storage`), then rent again | -| Channel | Default storage | Field | Units | +| Channel | Default storage | Field | Units (label) | | --- | --- | --- | --- | | Console | 10 GB | Instance disk size (UI) | GB | | REST search (`POST /api/v0/bundles/`) | 8 GB | `allocated_storage` | GB | | CLI (`vastai search offers`) | 5 GiB | `--storage` | GiB | -**Rule:** Set the same explicit storage in search and create-instance. REST create-instance `disk` must be ≥ **8 GB** when you pass it (omit uses platform defaults — do not assume the CLI search default of 5 is rentable via REST). Pass matching numeric values across channels when chaining CLI search → REST rent (CLI help labels GiB; REST fields are labeled GB). +**Match disk size when comparing prices.** Defaults differ by channel. When chaining CLI search → REST rent, use the **same integer** on both sides (for example `--storage 50` then `"disk": 50`) — the platform treats that number identically even though REST fields are labeled GB and CLI help says GiB. REST create-instance `disk` must be ≥ **8** when you pass it; do not assume the CLI default of 5 is rentable via REST. ## What happens after you rent @@ -302,7 +306,9 @@ No. Verification is a platform quality signal (see [Machine Tiers](/guides/insta ### Where do I see historical SLA credits? -Check **Account → Billing** and instance charges. SLA line items appear alongside compute charges for each settled day. +**Console:** After UTC settlement, open **Account → Billing** and look for SLA credit line items alongside compute charges. + +**API:** SLA settlement credits are **not** exposed in `GET /api/v0/charges/` today (documented charge `type` values: `gpu`, `disk`, `bwd`, `bwu`). Use the console for reconciliation until a client billing endpoint documents SLA settlement rows. Client webhooks for SLA credits are not available. Host-side settlement visibility uses [machine earnings](/api-reference/machines/show-earnings) (`sla_earn`) — that path is for hosts, not renters. ## Related documentation diff --git a/sdk/python/reference/create-instance.mdx b/sdk/python/reference/create-instance.mdx index cd9ab581..17e61a6c 100644 --- a/sdk/python/reference/create-instance.mdx +++ b/sdk/python/reference/create-instance.mdx @@ -5,6 +5,10 @@ sidebarTitle: "create_instance" Create a new instance from a contract offer ID. + +**SLA coverage:** `target_reliability` is not available on `create_instance()` today. Use the web console or REST `PUT /api/v0/asks/{id}/` to enable SLA — see [SLA Coverage](/guides/instances/choosing/sla-coverage#api-automation). + + ## Signature ```python From dd51622aed52cd76d4d80877fcb9124c6691e9d6 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:34:17 -0700 Subject: [PATCH 38/45] docs(sla): address doc-review consensus (cycle 12) Fix backtester confidence wording, create-instance offer-id labeling, and OpenAPI disk/lookback notes. Co-authored-by: Cursor --- api-reference/openapi.yaml | 10 ++++++++-- api-reference/openapi/yaml/create_instance.yaml | 3 ++- api-reference/openapi/yaml/sla_backtest.yaml | 3 ++- cli/reference/create-instance.mdx | 6 +++--- host/sla-backtester.mdx | 2 +- host/sla-offers.mdx | 4 ++-- snippets/host/cli/schedule-maint.mdx | 2 +- 7 files changed, 19 insertions(+), 11 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 3af10b99..dbca1c9c 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1638,7 +1638,9 @@ paths: disk: type: number format: float - description: 'Size of local disk partition (in GB) + minimum: 8 + description: 'Size of local disk partition (in GB). Minimum 8 when + specified. ' target_reliability: @@ -9258,7 +9260,11 @@ paths: description: 'Replays a machine''s historical compute earnings and uptime through SLA settlement math - to preview SLA charges and credits before listing with SLA. + to preview SLA charges and credits before listing with SLA. The maximum date + range is + + 366 days (inclusive); the default lookback is 90 days when custom dates are + omitted. Requires `machine_read` permission. See [SLA Earnings Backtester](/host/sla-backtester) diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index d5627f18..7d0bdb59 100644 --- a/api-reference/openapi/yaml/create_instance.yaml +++ b/api-reference/openapi/yaml/create_instance.yaml @@ -63,8 +63,9 @@ paths: disk: type: number format: float + minimum: 8 description: | - Size of local disk partition (in GB) + Size of local disk partition (in GB). Minimum 8 when specified. target_reliability: type: number format: float diff --git a/api-reference/openapi/yaml/sla_backtest.yaml b/api-reference/openapi/yaml/sla_backtest.yaml index 162264cd..542434a6 100644 --- a/api-reference/openapi/yaml/sla_backtest.yaml +++ b/api-reference/openapi/yaml/sla_backtest.yaml @@ -13,7 +13,8 @@ paths: operationId: slaBacktest description: | Replays a machine's historical compute earnings and uptime through SLA settlement math - to preview SLA charges and credits before listing with SLA. + to preview SLA charges and credits before listing with SLA. The maximum date range is + 366 days (inclusive); the default lookback is 90 days when custom dates are omitted. Requires `machine_read` permission. See [SLA Earnings Backtester](/host/sla-backtester) for usage guide. security: diff --git a/cli/reference/create-instance.mdx b/cli/reference/create-instance.mdx index 00b3bea5..fbfceb98 100644 --- a/cli/reference/create-instance.mdx +++ b/cli/reference/create-instance.mdx @@ -5,9 +5,9 @@ sidebarTitle: "create instance" Create a new instance - + **SLA coverage:** `target_reliability` is not available on this CLI command. Searching with a reliability target only quotes pricing — use the web console or REST create-instance to enable SLA. See [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers). - + ## Usage @@ -18,7 +18,7 @@ vastai create instance ID [OPTIONS] [--args ...] ## Arguments - id of instance type to launch (returned from search offers) + Offer/ask ID from search offers (the value passed to create-instance / `PUT /api/v0/asks/{id}/`). This is not a running instance ID. ## Options diff --git a/host/sla-backtester.mdx b/host/sla-backtester.mdx index ae094624..eac84b9c 100644 --- a/host/sla-backtester.mdx +++ b/host/sla-backtester.mdx @@ -258,7 +258,7 @@ The backtester accepts **`p`** (confidence) instead of `sla_sigma_x`. The mappin | `0.6667` | Normal (default) | `sla_sigma_x ≈ 0.5` | | `0.50` | Wide | `sla_sigma_x ≈ 1.0` | -Higher confidence (higher `p`) → tighter spread → lower simulated SLA charges for clients at a given target (more competitive `dph_total`). Tighter `p` does **not** reduce credit owed on a miss — use `worst_day_loss` and `reliability=` overrides to model settlement exposure. +Tighter confidence (higher `p`) does **not** reduce credit owed on a miss — use `worst_day_loss` and `reliability=` overrides to model settlement exposure. ## Error responses diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 0c5686ee..1d4bddc0 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -48,7 +48,7 @@ On outage days you may still bill clients for **intended** compute **and** owe S -**Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. Interruptible instances on an SLA-enabled machine are not SLA-covered; on-demand contracts on the same machine are. If a client attempts to reserve or prepay an SLA-enabled offer, the request is rejected. +**Rental types:** SLA applies to **on-demand rentals only**. It does not apply to interruptible/bid instances or reserved/prepay rentals. Interruptible instances on an SLA-enabled machine are not SLA-covered; on-demand contracts on the same machine are. Reserved or prepay attempts on an SLA-enabled offer are not supported — use on-demand to rent with SLA. - Optional: run the [backtester](/host/sla-backtester) after you have weeks of history; otherwise use the web console SLA preview and the economics walkthrough on this page. @@ -467,7 +467,7 @@ Clients pay more because you admit greater uncertainty. Use this if your reliabi **Planned SLA maintenance (may earn credit):** Schedule at least 24 hours in advance with [`vastai schedule maint`](/host/cli/schedule-maint) (or the [REST schedule-maintenance API](/api-reference/machines/schedule-maint)). Include `--sdate` and `--duration`. Advance notice (not the category value) is what makes maintenance “planned” for SLA credit review. Valid `--maintenance_category` values: `power`, `internet`, `disk`, `gpu`, `software`, `other`. Credit eligibility is evaluated on a case-by-case basis. -**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC. **CLI `--duration` is in hours.** Schedule maintenance **sequentially** across a fleet — the API is rate-limited (~2.5 requests/second). On HTTP 429, wait and retry with backoff (for example, `sleep 2` between machines). +**CLI `--sdate` uses Unix epoch seconds (UTC)**; the REST body uses ISO 8601 UTC. **CLI `--duration` is in hours.** Schedule maintenance **sequentially** across a fleet. On HTTP 429, wait and retry with backoff (for example, `sleep 2` between machines). See [Rate Limits and Errors](/api-reference/rate-limits-and-errors). ```bash # Planned window: 2026-08-01 02:00:00 UTC (≥24 hours ahead when you run this) diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 432a4d2a..0438a47b 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -60,7 +60,7 @@ If the machine must go offline without adequate notice, still run `schedule main vastai schedule maint MACHINE_ID --sdate "$(date -u +%s)" --duration 1 --maintenance_category power ``` -To cancel a scheduled window, use [`vastai cancel maint`](/host/cli/cancel-maint). To reschedule, cancel first, then schedule a new window (≥24 hours ahead for planned SLA credit review). Across many machines, schedule sequentially and back off on HTTP 429 (~2.5 req/s). +To cancel a scheduled window, use [`vastai cancel maint`](/host/cli/cancel-maint). To reschedule, cancel first, then schedule a new window (≥24 hours ahead for planned SLA credit review). Across many machines, schedule sequentially and back off on HTTP 429. ## Examples From 4d8acd3cc5d8c83fe78f66fb7a78823d58e01e90 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:39:29 -0700 Subject: [PATCH 39/45] docs(sla): address doc-review consensus (cycle 13) Surface client billing reconciliation limits early and align create-instance CLI examples with shipped vastai. Co-authored-by: Cursor --- api-reference/openapi.yaml | 4 ++-- api-reference/openapi/yaml/create_instance.yaml | 2 +- guides/instances/choosing/find-and-rent.mdx | 2 +- guides/instances/choosing/sla-coverage.mdx | 12 +++++++----- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index dbca1c9c..9c3f490a 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1592,8 +1592,8 @@ paths: \ CLI and SDK cannot pass this field until support ships. Use the web console\ \ or `PUT /api/v0/asks/{id}/` with `target_reliability` in the request body\ \ to enable SLA coverage \u2014 see [SLA Coverage](/guides/instances/choosing/sla-coverage).\n\ - \nCLI Usage: `vastai create instance [options]` (no `target_reliability`\ - \ flag today)" + \nCLI Usage: `vastai create instance --image [options]`\ + \ (no `target_reliability` flag today)" security: - BearerAuth: [] tags: diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index 7d0bdb59..191ed058 100644 --- a/api-reference/openapi/yaml/create_instance.yaml +++ b/api-reference/openapi/yaml/create_instance.yaml @@ -25,7 +25,7 @@ paths: **SLA note:** `target_reliability` is REST-only at rent time. The published CLI and SDK cannot pass this field until support ships. Use the web console or `PUT /api/v0/asks/{id}/` with `target_reliability` in the request body to enable SLA coverage — see [SLA Coverage](/guides/instances/choosing/sla-coverage). - CLI Usage: `vastai create instance [options]` (no `target_reliability` flag today) + CLI Usage: `vastai create instance --image [options]` (no `target_reliability` flag today) security: - BearerAuth: [] tags: diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index f56dcd5e..4e8298ee 100644 --- a/guides/instances/choosing/find-and-rent.mdx +++ b/guides/instances/choosing/find-and-rent.mdx @@ -58,7 +58,7 @@ All stats shown are the portion of the total machine rented. - Max Duration: The maximum length of a rental contract on this machine - Reliability Score: A measure of the machine's historical uptime and health. All machines start at 60%. This is **not** the host SLA claim. - Rental Option: RENT button -- **SLA (optional):** Available on **on-demand** rentals only. Set a **reliability target** in Search, then confirm the price breakdown includes an **SLA charge** line before clicking **RENT**. Host SLA claim (`expected_reliability`) does not protect you unless you opt in — see [SLA Coverage](/guides/instances/choosing/sla-coverage). +- **SLA (optional):** On-demand offers may include an optional SLA upsell. The host’s advertised SLA claim (not the Reliability Score above) sets the ceiling for your target. Confirm an **SLA charge** line before **RENT** — see [SLA Coverage](/guides/instances/choosing/sla-coverage). ## Instance Disk Size diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index b0ac6330..5ba51dd1 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -23,7 +23,7 @@ This page explains SLA from the renter side: how to find SLA offers, how pricing | Rent with SLA in the console | [Finding SLA offers → In the web console](#in-the-web-console) | | I use only the CLI today | **Cannot enable SLA at rent time** — CLI search only quotes pricing. After rent, verify with `vastai show instances --raw` (`target_reliability` > 0). To enable coverage, use the console or [API automation](#api-automation) (REST) | | Understand charges and credits | [How pricing works](#how-pricing-works) → [What happens after you rent](#what-happens-after-you-rent) | -| Automate search → rent → verify | [API automation](#api-automation) (REST) | +| Automate search → rent → verify | [API automation](#api-automation) (REST). **Billing reconciliation:** SLA settlement credits appear in the console billing UI today — not in `GET /api/v0/charges/` or client webhooks | SLA applies to **on-demand rentals only** — not interruptible/bid or reserved/prepay contracts. See [Instance Pricing](/guides/instances/pricing). @@ -61,7 +61,7 @@ Bandwidth is billed separately from usage (`inet_*` rates) and is **not** includ | Host SLA claim | Maximum reliability the host advertises on the listing (`expected_reliability`). Higher claim → lower SLA charge at a given target | | Host confidence | Host-side pricing setting that affects SLA charge size. **You do not set this** — the host chooses it, and it is **not shown on offer cards**. Compare offers using `dph_total` or the SLA charge line in the price breakdown | -**Rule of thumb:** pick a target **at or below** the host's claim for the best value. Asking for 99% coverage on a host who only claims 95% costs much more than asking for 95% on a host who claims 99%. +**Rule of thumb:** pick a target **at or below** the host's claim for the best value. Asking for 99% coverage on a host who only claims 95% costs much more than asking for 95% on a host who claims 99%. In search results, the host claim appears as **expected reliability** / SLA claim on the offer (API: `expected_reliability`) — not the Reliability Score on the card. ### Example: H100 at $3.50/hr GPU @@ -141,6 +141,8 @@ Always compare **`dph_total`**, not just GPU price, when SLA matters. Sort by `d Console-only renters can skip this section — use [In the web console](#in-the-web-console) above. +**Billing reconciliation:** SLA settlement credits appear in the console billing UI today. They are not included in `GET /api/v0/charges/` and client webhooks for SLA credits are not available — plan manual console reconciliation after UTC settlement (see [FAQ](#where-do-i-see-historical-sla-credits)). + **1. Search** (prices `dph_total` at your target — include storage explicitly so quotes are comparable): ```bash @@ -278,9 +280,9 @@ To find SLA-covered instances, filter **client-side** from the show-instances re | --- | --- | | Your reliability target | `target_reliability` | | SLA charge rate | `search.slaPremiumPerHour` / `instance.slaPremiumPerHour` | -| Host SLA claim (offers / contracts) | `expected_reliability` / `sla_r_claim` | +| Host SLA claim (offers / contracts) | `expected_reliability` | -Host confidence is a host-side pricing setting and is **not shown on offer cards** — compare offers using `dph_total` or the SLA charge line. Confirm field names against a live `--raw` response before building parsers. +Host ask field `sla_r_claim` is host-side only — see [SLA Offers](/host/sla-offers). Host confidence is **not shown on offer cards** — compare offers using `dph_total` or the SLA charge line. Confirm field names against a live `--raw` response before building parsers.
## When SLA is not available @@ -308,7 +310,7 @@ No. Verification is a platform quality signal (see [Machine Tiers](/guides/insta **Console:** After UTC settlement, open **Account → Billing** and look for SLA credit line items alongside compute charges. -**API:** SLA settlement credits are **not** exposed in `GET /api/v0/charges/` today (documented charge `type` values: `gpu`, `disk`, `bwd`, `bwu`). Use the console for reconciliation until a client billing endpoint documents SLA settlement rows. Client webhooks for SLA credits are not available. Host-side settlement visibility uses [machine earnings](/api-reference/machines/show-earnings) (`sla_earn`) — that path is for hosts, not renters. +**API:** SLA settlement credits are **not** exposed in `GET /api/v0/charges/` today (documented charge `type` values: `gpu`, `disk`, `bwd`, `bwu`). Use the console for reconciliation until a client billing endpoint documents SLA settlement rows. Client webhooks for SLA credits are not available. Host-side settlement visibility uses [machine earnings](/api-reference/billing/show-earnings) (`sla_earn`) — that path is for hosts, not renters. ## Related documentation From 45c7feb7d848b1ca3d13cdb1987bfd304284a8a3 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:47:22 -0700 Subject: [PATCH 40/45] docs(sla): use vastai in create-instance OpenAPI examples Co-authored-by: Cursor --- api-reference/openapi/yaml/create_instance.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index 191ed058..7db5e9ee 100644 --- a/api-reference/openapi/yaml/create_instance.yaml +++ b/api-reference/openapi/yaml/create_instance.yaml @@ -343,6 +343,6 @@ x-cli-commands: endpoint: /api/v0/asks/{id}/ method: PUT examples: - - vast create instance 1234567 --image tensorflow/tensorflow:latest-gpu --disk 32 - - vast create instance 1234567 --template abc123def456 - - vast create instance 1234567 --price 0.4 --disk 100 --env JUPYTER_TOKEN=abc123 \ No newline at end of file + - vastai create instance 1234567 --image tensorflow/tensorflow:latest-gpu --disk 32 + - vastai create instance 1234567 --template abc123def456 + - vastai create instance 1234567 --price 0.4 --disk 100 --env JUPYTER_TOKEN=abc123 \ No newline at end of file From 00df4b202cdb22dd04b64f0e826bfc1d4272edff Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 09:48:09 -0700 Subject: [PATCH 41/45] docs(sla): address doc-review consensus (cycle 14) Clarify self-test billing, add host checklist and SLA key recipe, and fix offer-id / date platform notes. Co-authored-by: Cursor --- api-reference/permissions.mdx | 17 +++++++++++++++++ guides/instances/choosing/sla-coverage.mdx | 12 ++++++------ host/hosting-overview.mdx | 4 ++-- host/sla-offers.mdx | 10 ++++++++++ sdk/python/reference/create-instance.mdx | 2 +- snippets/host/cli/list-machine.mdx | 2 +- snippets/host/cli/schedule-maint.mdx | 2 ++ snippets/host/sdk/list-machine.mdx | 2 +- 8 files changed, 40 insertions(+), 11 deletions(-) diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx index cb08e0b6..a1355fdf 100644 --- a/api-reference/permissions.mdx +++ b/api-reference/permissions.mdx @@ -208,6 +208,23 @@ Below is the complete mapping of which endpoints each permission category contro - [Unlist Machine](/api-reference/machines/unlist-machine) - [Unlist Volume](/api-reference/volumes/unlist-volume) +**Host SLA scoped-key recipe (minimum):** + +```json +{ + "machine_read": {}, + "machine_write": {}, + "billing_read": {} +} +``` + +| Task | Permission | Console fallback | +| --- | --- | --- | +| List/update SLA via `create_asks` | `machine_write` | **Set Pricing → SLA** → LIST | +| SLA backtester | `machine_read` | Console SLA preview | +| Schedule / cancel maintenance | `machine_write` | None (CLI/REST only) | +| Monitor `sla_earn` | `billing_read` | Host → Billing / Earnings | + ### misc - [Show Workergroups](/api-reference/serverless/show-workergroup) diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 5ba51dd1..332c0db5 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -276,13 +276,13 @@ Show-instances output may include `target_reliability` and price fields under `s To find SLA-covered instances, filter **client-side** from the show-instances response (`target_reliability > 0`, `instance.slaPremiumPerHour`). Prefer client-side filtering in production. OpenAPI documents optional `select_filters` on stored fields such as `sla_r_target` / `target_reliability` when present; computed fields (for example `has_sla`) are not filterable. Do not rely on `select_filters` alone for SLA detection. -| Client-visible concept | API / raw field | -| --- | --- | -| Your reliability target | `target_reliability` | -| SLA charge rate | `search.slaPremiumPerHour` / `instance.slaPremiumPerHour` | -| Host SLA claim (offers / contracts) | `expected_reliability` | +| Client-visible concept | Search / bundles | Active rental (`GET /api/v1/instances/`) | +| --- | --- | --- | +| Your reliability target | `target_reliability` (quote only until rent) | `target_reliability` | +| SLA charge rate | `search.slaPremiumPerHour` | `instance.slaPremiumPerHour` | +| Host SLA claim | `expected_reliability` | `sla_r_claim` | -Host ask field `sla_r_claim` is host-side only — see [SLA Offers](/host/sla-offers). Host confidence is **not shown on offer cards** — compare offers using `dph_total` or the SLA charge line. Confirm field names against a live `--raw` response before building parsers. +Host ask field `sla_r_claim` on listings is host-side; on active rentals the locked claim appears as `sla_r_claim` in show-instances. Host confidence is **not shown on offer cards** — compare offers using `dph_total` or the SLA charge line. Confirm field names against a live `--raw` response before building parsers.
## When SLA is not available diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index cd74edb3..bc4133e1 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -213,7 +213,7 @@ To rent your own machine you will need to first search the offers with your mach ./vastai show machines ``` -Then for each machine id you will need to find the available instance IDs. +Then for each machine id you will need to find the available **offer/ask IDs** (not running instance IDs). ```text Text ./vastai search offers 'machine_id=12345 verified=any' @@ -221,7 +221,7 @@ Then for each machine id you will need to find the available instance IDs. Replace 12345 with your actual machine ID in question. You can see the number of available listings as well as information about the machine. This is the fastest way to also see all the offers listed for a given machine. The website GUI stacks similar offers and so it is not easy to see all the listings for a given machine. That is not a problem for the CLI. -Take the ID number from the first column and use that to create a free instance on your own machine. This example loads the latest pytorch image along with both jupyter and ssh direct launch modes. +Take the **offer/ask ID** from the first column of search results and use it with `create instance`. This creates a **test rental billed to your separate client account** like any other rental (it is not free). Host earnings offset client spend only after rentals settle. This example loads the latest pytorch image along with both jupyter and ssh direct launch modes. ```text Text vastai create instance --image pytorch/pytorch:latest --jupyter --direct --env '-e TZ=PDT -p 22:22 -p 8080:8080' diff --git a/host/sla-offers.mdx b/host/sla-offers.mdx index 1d4bddc0..78c1e9aa 100644 --- a/host/sla-offers.mdx +++ b/host/sla-offers.mdx @@ -25,6 +25,16 @@ SLA settlement is **asymmetric by design**: when reliability is strong relative | I list with CLI only (no SLA flags yet) | **Set Pricing → SLA** + **LIST** in the console, or REST `PUT /api/v0/machines/create_asks/` — SLA flags are **not** in `vastai list machine` yet | | Monitor settlement after listing | [Monitoring SLA after listing](#monitoring-sla-after-listing) | +## SLA host checklist + +1. Complete [host setup](https://cloud.vast.ai/host/setup/) and list your machine. +2. Test on a [separate client account](/host/hosting-overview#testing-your-own-machine) (billed like any rental). +3. Install the [CLI](/cli/hello-world) (required for SLA maintenance scheduling). +4. Confirm SLA account access (**Set Pricing → SLA** panel visible; if missing, contact support). +5. Preview economics (console SLA panel or [backtester](/host/sla-backtester)), then set claim/confidence. +6. Enable SLA listing and verify in search (`machine_id=` filter). +7. Read [Scheduled maintenance](#scheduled-maintenance) before your first SLA rental. + ## Before you enable SLA diff --git a/sdk/python/reference/create-instance.mdx b/sdk/python/reference/create-instance.mdx index 17e61a6c..379c8e88 100644 --- a/sdk/python/reference/create-instance.mdx +++ b/sdk/python/reference/create-instance.mdx @@ -41,7 +41,7 @@ VastAI.create_instance( ## Parameters - ID of the offer/contract to create the instance from (returned by search_offers). + Offer/ask ID from search offers (same value as CLI create-instance). This is not a running instance ID. diff --git a/snippets/host/cli/list-machine.mdx b/snippets/host/cli/list-machine.mdx index 342620c6..863b1404 100644 --- a/snippets/host/cli/list-machine.mdx +++ b/snippets/host/cli/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent. This is a **host** command, used for managing machines you are renting out on Vast.ai. -SLA listing flags are not in the published CLI yet — see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration options (`-v`, `-z`, `-l`) work today. +SLA listing flags are not in the published CLI yet — prefer console **Set Pricing → SLA**, or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration options (`-v`, `-z`, `-l`) work today. ## Usage diff --git a/snippets/host/cli/schedule-maint.mdx b/snippets/host/cli/schedule-maint.mdx index 0438a47b..e4dbddc9 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -46,6 +46,8 @@ If SLA is enabled and you need planned downtime during an active rental, schedul ```bash # Replace MACHINE_ID; --sdate must be a future UTC epoch (≥24h ahead for planned credit review) +# Linux: date -u -d '2026-08-01 02:00:00' +%s +# macOS: date -u -j -f '%Y-%m-%d %H:%M:%S' '2026-08-01 02:00:00' +%s vastai schedule maint MACHINE_ID \ --sdate "$(date -u -d '2026-08-01 02:00:00' +%s)" \ --duration 2 \ diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index 341376ae..583ab8e8 100644 --- a/snippets/host/sdk/list-machine.mdx +++ b/snippets/host/sdk/list-machine.mdx @@ -3,7 +3,7 @@ Lists a machine for rent with optional pricing and configuration parameters. This is a **host** method, used for managing machines you are renting out on Vast.ai. -SLA listing parameters are not in the published Python SDK yet — see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing options are CLI-only today. +SLA listing parameters are not in the published Python SDK yet — prefer console **Set Pricing → SLA**, or REST; see [SLA Offers](/host/sla-offers#api-for-automation). Volume/duration listing options are CLI-only today. ## Signature From 187f5b8d3f443415dfd83ed6488c76b3e36abd61 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 10:05:47 -0700 Subject: [PATCH 42/45] docs(sla): address doc-review consensus (cycle 15) Wrap host SLA scoped-key JSON in required api object and fix create-instance example fences. Co-authored-by: Cursor --- api-reference/permissions.mdx | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx index a1355fdf..a8ba08db 100644 --- a/api-reference/permissions.mdx +++ b/api-reference/permissions.mdx @@ -208,13 +208,15 @@ Below is the complete mapping of which endpoints each permission category contro - [Unlist Machine](/api-reference/machines/unlist-machine) - [Unlist Volume](/api-reference/volumes/unlist-volume) -**Host SLA scoped-key recipe (minimum):** +**Host SLA scoped-key recipe (minimum):** Create via [Create API Key](/api-reference/accounts/create-api-key). See [Creating Scoped Keys](#creating-scoped-keys) for the required `api` wrapper. ```json { - "machine_read": {}, - "machine_write": {}, - "billing_read": {} + "api": { + "machine_read": {}, + "machine_write": {}, + "billing_read": {} + } } ``` @@ -225,6 +227,20 @@ Below is the complete mapping of which endpoints each permission category contro | Schedule / cancel maintenance | `machine_write` | None (CLI/REST only) | | Monitor `sla_earn` | `billing_read` | Host → Billing / Earnings | +**Client SLA search → REST rent (minimum):** + +```json +{ + "api": { + "misc": {}, + "instance_write": {}, + "instance_read": {} + } +} +``` + +SLA settlement credits are console-only for renters today — `billing_read` does not expose client SLA credit rows in `GET /api/v0/charges/`. + ### misc - [Show Workergroups](/api-reference/serverless/show-workergroup) From ee6c1d7c4ab5d8bb6d13300c492300145fcc148f Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 10:12:14 -0700 Subject: [PATCH 43/45] docs(sla): fix create-instance example fences (cycle 15 follow-up) Co-authored-by: Cursor --- cli/reference/create-instance.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/cli/reference/create-instance.mdx b/cli/reference/create-instance.mdx index fbfceb98..e71bbe2c 100644 --- a/cli/reference/create-instance.mdx +++ b/cli/reference/create-instance.mdx @@ -133,7 +133,7 @@ Performs the same action as pressing the "RENT" button on the website at https:/ Creates an instance from an offer ID (which is returned from "search offers"). Each offer ID can only be used to create one instance. Besides the offer ID, you must pass in an '`--image`' argument as a minimum. -If you use args/entrypoint launch mode, we create a container from your image as is, without attempting to inject ssh and or jupyter. +If you use args/entrypoint launch mode, we create a container from your image as is, without attempting to inject SSH or Jupyter. If you use the args launch mode, you can override the entrypoint with `--entrypoint`, and pass arguments to the entrypoint with `--args`. If you use `--args`, that must be the last argument, as any following tokens are consumed into the args string. For ssh/jupyter launch types, use `--onstart-cmd` to pass in startup script, instead of `--entrypoint` and `--args`. @@ -147,18 +147,20 @@ vastai create instance 384826 --template_hash 661d064bbda1f2a133816b6d55da07c3 - # create an on-demand instance with the pytorch/pytorch image, 40GB of disk, open 8081 udp, direct ssh, set hostname to billybob, and a small onstart script vastai create instance 6995713 --image pytorch/pytorch --disk 40 --env '-p 8081:8081/udp -h billybob' --ssh --direct --onstart-cmd "env | grep _ >> /etc/environment; echo 'starting up'"; -# create an on-demand instance with the bobsrepo/pytorch:latest image, 20GB of disk, open 22, 8080, jupyter ssh, and set some env variables -vastai create instance 384827 --image bobsrepo/pytorch:latest --login '-u bob -p 9d8df!fd89ufZ docker.io' --jupyter --direct --env '-e TZ=PDT -e XNAME=XX4 -p 22:22 -p 8080:8080' --disk 20 +# create an on-demand instance with a private image (use your registry password, not a real secret in docs) +vastai create instance 384827 --image YOUR_REGISTRY/pytorch:latest --login '-u YOUR_USER -p YOUR_PASSWORD docker.io' --jupyter --direct --env '-e TZ=PDT -e XNAME=XX4 -p 22:22 -p 8080:8080' --disk 20 # create an on-demand instance with the pytorch/pytorch image, 40GB of disk, override the entrypoint to bash and pass bash a simple command to keep the instance running. (args launch without ssh/jupyter) vastai create instance 5801802 --image pytorch/pytorch --disk 40 --onstart-cmd 'bash' --args -c 'echo hello; sleep infinity;' # create an interruptible (spot) instance with the PyTorch (cuDNN Devel) template, 64GB of disk, and a bid price of $0.10/hr vastai create instance 384826 --template_hash 661d064bbda1f2a133816b6d55da07c3 --disk 64 --bid_price 0.1 +``` + +Return value — JSON reporting the instance ID of the newly created instance: -Return value: -Returns a json reporting the instance ID of the newly created instance: -{'success': True, 'new_contract': 7835610} +```json +{"success": true, "new_contract": 7835610} ``` ## Global Options From 91b3583d8b2a419cec490ce0617660dd9089eecc Mon Sep 17 00:00:00 2001 From: rfernandez Date: Mon, 27 Jul 2026 10:12:52 -0700 Subject: [PATCH 44/45] docs(sla): address doc-review consensus (cycle 16) Align instances pagination defaults, document SLA search CLI warnings, and relocate client key recipe. Co-authored-by: Cursor --- api-reference/openapi.yaml | 7 +++-- .../openapi/yaml/show_instances.yaml | 4 +-- api-reference/permissions.mdx | 28 +++++++++---------- cli/reference/search-offers.mdx | 5 ++++ guides/instances/choosing/sla-coverage.mdx | 4 +-- host/hosting-overview.mdx | 4 +-- 6 files changed, 29 insertions(+), 23 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 9c3f490a..c22d172f 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -8068,11 +8068,12 @@ paths: - name: limit in: query required: false - description: "Instances per page. Default 25, max 25. Values \u2264 0 are\ - \ treated as 5." + description: "Instances per page. Maximum 25. Omit or set \u2264 0 to use\ + \ the server default (currently 5). Prefer an explicit `limit` (for example\ + \ 25)." schema: type: integer - default: 25 + default: 5 maximum: 25 example: 25 - name: after_token diff --git a/api-reference/openapi/yaml/show_instances.yaml b/api-reference/openapi/yaml/show_instances.yaml index 08f768fc..c2f0a921 100644 --- a/api-reference/openapi/yaml/show_instances.yaml +++ b/api-reference/openapi/yaml/show_instances.yaml @@ -21,10 +21,10 @@ paths: - name: limit in: query required: false - description: Instances per page. Default 25, max 25. Values ≤ 0 are treated as 5. + description: Instances per page. Maximum 25. Omit or set ≤ 0 to use the server default (currently 5). Prefer an explicit `limit` (for example 25). schema: type: integer - default: 25 + default: 5 maximum: 25 example: 25 - name: after_token diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx index a8ba08db..24a21a7e 100644 --- a/api-reference/permissions.mdx +++ b/api-reference/permissions.mdx @@ -227,20 +227,6 @@ Below is the complete mapping of which endpoints each permission category contro | Schedule / cancel maintenance | `machine_write` | None (CLI/REST only) | | Monitor `sla_earn` | `billing_read` | Host → Billing / Earnings | -**Client SLA search → REST rent (minimum):** - -```json -{ - "api": { - "misc": {}, - "instance_write": {}, - "instance_read": {} - } -} -``` - -SLA settlement credits are console-only for renters today — `billing_read` does not expose client SLA credit rows in `GET /api/v0/charges/`. - ### misc - [Show Workergroups](/api-reference/serverless/show-workergroup) @@ -254,6 +240,20 @@ SLA settlement credits are console-only for renters today — `billing_read` doe - [Search Offers](/api-reference/search/search-offers) - [Search Volumes](/api-reference/volumes/search-volumes) +**Client SLA search → REST rent (minimum):** Create via [Create API Key](/api-reference/accounts/create-api-key) with the `api` wrapper below (`misc` covers bundles search). + +```json +{ + "api": { + "misc": {}, + "instance_write": {}, + "instance_read": {} + } +} +``` + +Published OpenAPI charge `type` values for `GET /api/v0/charges/` are `gpu`, `disk`, `bwd`, and `bwu`. Prefer **Account → Billing** in the console for SLA settlement credit reconciliation until client charge schemas document SLA line items. + ### team\_read - [Show Team Members](/api-reference/team/show-team-members) diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index fa3d277f..97fc9255 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -157,6 +157,11 @@ vastai search offers 'cpu_arch=arm64' | `expected_reliability` | float | host’s advertised SLA reliability claim on the offer | | `has_sla` | bool | restrict to offers with SLA enabled (`true`) or without (`false`) | | `target_reliability` | float | desired SLA coverage (0–1 exclusive); prices `dph_total` in search only — see [SLA Coverage](/guides/instances/choosing/sla-coverage#finding-sla-offers) to enable at rent | + + +SLA query keys (`has_sla`, `expected_reliability`, `target_reliability`) are accepted by search. Older CLI builds may print a stderr warning that a field is unrecognized while still applying the filter — prefer a current CLI, or ignore the warning when results look correct. + + | `rentable` | bool | is the instance currently rentable | | `rented` | bool | allow/disallow duplicates and potential conflicts with existing stopped instances | | `storage_cost` | float | storage cost in $/GB/month | diff --git a/guides/instances/choosing/sla-coverage.mdx b/guides/instances/choosing/sla-coverage.mdx index 332c0db5..1efdb0b3 100644 --- a/guides/instances/choosing/sla-coverage.mdx +++ b/guides/instances/choosing/sla-coverage.mdx @@ -179,7 +179,7 @@ See [Create Instance](/api-reference/instances/create-instance) and [Search Offe **API key permissions:** create a scoped key with `misc` (search/bundles), `instance_write` (create-instance), and preferably `instance_read` (verify show-instances). See [Authentication](/api-reference/authentication) and [Permissions](/api-reference/permissions). -**3. Verify** via `GET /api/v1/instances/` or `vastai show instances --raw`: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. `GET /api/v1/instances/` returns at most 25 instances per request — paginate by passing each response’s `next_token` as the **`after_token`** query parameter until `next_token` is null. +**3. Verify** via `GET /api/v1/instances/` or `vastai show instances --raw`: confirm `target_reliability > 0`. For running instances, check `instance.slaPremiumPerHour`; search-context snapshots use `search.slaPremiumPerHour`. Requires `instance_read`. Pass an explicit `limit` (default can be as low as **5**; maximum **25** per request). Paginate by passing each response’s `next_token` as the **`after_token`** query parameter until `next_token` is null. | Symptom | Typical response | What to do | | --- | --- | --- | @@ -310,7 +310,7 @@ No. Verification is a platform quality signal (see [Machine Tiers](/guides/insta **Console:** After UTC settlement, open **Account → Billing** and look for SLA credit line items alongside compute charges. -**API:** SLA settlement credits are **not** exposed in `GET /api/v0/charges/` today (documented charge `type` values: `gpu`, `disk`, `bwd`, `bwu`). Use the console for reconciliation until a client billing endpoint documents SLA settlement rows. Client webhooks for SLA credits are not available. Host-side settlement visibility uses [machine earnings](/api-reference/billing/show-earnings) (`sla_earn`) — that path is for hosts, not renters. +**API:** Prefer **Account → Billing** for SLA settlement credit reconciliation. Published OpenAPI for `GET /api/v0/charges/` documents charge `type` values `gpu`, `disk`, `bwd`, and `bwu` — not a dedicated SLA settlement type. Client webhooks for SLA credits are not available. Host-side settlement visibility uses [machine earnings](/api-reference/billing/show-earnings) (`sla_earn`) — that path is for hosts, not renters. ## Related documentation diff --git a/host/hosting-overview.mdx b/host/hosting-overview.mdx index bc4133e1..a322f43b 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -199,9 +199,9 @@ If you have raised the pricing, you cannot extend the current rental contracts. It is vital to test your own machine to ensure the ports and software are running smoothly. -### Setup a separate client account +### Set up a separate client account -There are two supported ways to test your own machine. If you want to use the website GUI, you will need to setup a new account on a different email address, add a credit card and then find your machine and create instances on it like a client. This has the benefit of showing you the entire client experience. Testing the recommended Pytorch template is vital to ensure that SSH and Jupyter are working properly. +There are two supported ways to test your own machine. If you want to use the website GUI, you will need to set up a new account on a different email address, add a credit card and then find your machine and create instances on it like a client. This has the benefit of showing you the entire client experience. Testing the recommended PyTorch template is vital to ensure that SSH and Jupyter are working properly. ### Use the CLI (preferred) From 457109cc76aa447f9635ef8e8e078595e640c120 Mon Sep 17 00:00:00 2001 From: rfernandez Date: Tue, 28 Jul 2026 09:28:49 -0700 Subject: [PATCH 45/45] fix(openapi): rebuild combined OpenAPI to sync CI Regenerate openapi.yaml so nullable types and unique operationIds match the yaml sources and pass verify-openapi / mint openapi-check. Co-authored-by: Cursor --- api-reference/openapi.yaml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index c22d172f..383d1e6e 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -8430,22 +8430,25 @@ paths: when applicable). example: 0.8021 target_reliability: - type: number + type: + - number + - 'null' format: float - nullable: true description: Client SLA coverage target locked at rent time. Null or 0 when the rental has no SLA. example: 0.95 sla_r_claim: - type: number + type: + - number + - 'null' format: float - nullable: true description: Host reliability claim for this SLA contract. example: 0.99 sla_sigma_x: - type: number + type: + - number + - 'null' format: float - nullable: true description: Host confidence spread for this SLA contract. example: 0.5 dlperf: @@ -9378,9 +9381,10 @@ paths: type: number format: float reliability: - type: number + type: + - number + - 'null' format: float - nullable: true beta: type: number format: float @@ -9476,7 +9480,6 @@ paths: description: "Too Many Requests \u2014 rate limit exceeded" tags: - Host - operationId: slaBacktest /api/v0/deployment/{id}/start: post: summary: start deployment