diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 5f36a511..383d1e6e 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 --image [options]`\ + \ (no `target_reliability` flag today)" security: - BearerAuth: [] tags: @@ -1646,7 +1638,31 @@ 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: + 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`. + + 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: @@ -1774,6 +1790,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 @@ -1791,7 +1809,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: @@ -4496,13 +4523,16 @@ 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 pricing, minimum GPU requirements, end date and discount rates. - - - CLI Usage: `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_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: @@ -4549,6 +4579,48 @@ paths: type: number format: float description: Maximum discount rate allowed for prepaid credits + sla_r_claim: + type: number + format: float + minimum: 0 + maximum: 0.9999 + 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 on new rentals. + + ' + 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 when enabling SLA.\n" + sla_max_beta: + type: number + format: float + 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 + 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; ignored on asks. responses: '200': description: Successful response @@ -4559,15 +4631,44 @@ 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_claim: 0.99 + sla_sigma_x: 0.5 + results: + - machine_id: 12345 + user_id: 67890 + extended: 1 + new_contracts: [] + upd_contracts: + - 1 '400': description: Bad Request content: @@ -4577,12 +4678,32 @@ paths: properties: error: type: string - example: invalid_args + enum: + - invalid_args + - invalid_sla_params + - sla_not_approved + - sla_daemon_outdated + example: invalid_sla_params + msg: + type: string + example: No such machine(s) for your account + '401': + description: "Unauthorized \u2014 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: Invalid machine id or parameters + example: Your key lacks the machine_write permission group '403': - description: Forbidden + description: "Forbidden \u2014 machine locked" content: application/json: schema: @@ -4590,10 +4711,12 @@ paths: properties: error: type: string - example: not_authorized + enum: + - machine_locked + example: machine_locked msg: type: string - example: Only machine owner can create ask contracts + example: Machine is decommissioned or migration-locked tags: - Machines operationId: listMachine @@ -6270,8 +6393,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. @@ -6519,8 +6650,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. 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 + (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, @@ -6721,7 +6875,7 @@ paths: ' example: limit: 100 - type: on-demand + type: ondemand verified: eq: true rentable: @@ -6819,7 +6973,7 @@ paths: vram_costperhour: 0.009876 webpage: null vms_enabled: false - expected_reliability: 0.5 + expected_reliability: 0.99 is_vm_deverified: false resource_type: gpu cluster_id: null @@ -6838,12 +6992,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 @@ -7742,6 +7898,11 @@ paths: 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`. + + CLI Usage: `vastai show earnings [options]`' security: - BearerAuth: [] @@ -7756,12 +7917,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: @@ -7791,6 +7962,9 @@ paths: type: number total_bwd: type: number + total_sla: + type: number + description: Net SLA earnings over the requested window. username: type: string email: @@ -7835,6 +8009,10 @@ 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: @@ -7850,6 +8028,11 @@ 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 the SLA charge; negative when the + host credits the client. '400': description: Bad Request - Invalid input syntax content: @@ -7885,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 @@ -7926,8 +8110,15 @@ 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. + + 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: @@ -8235,7 +8426,31 @@ paths: dph_total: type: number format: float + description: Total $/hour including storage (and SLA charge + when applicable). example: 0.8021 + target_reliability: + type: + - number + - 'null' + format: float + 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 + - 'null' + format: float + description: Host reliability claim for this SLA contract. + example: 0.99 + sla_sigma_x: + type: + - number + - 'null' + format: float + description: Host confidence spread for this SLA contract. + example: 0.5 dlperf: type: - number @@ -8289,17 +8504,38 @@ 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 @@ -8709,11 +8945,11 @@ paths: /api/v0/machines: get: summary: show machines - description: 'Fetches data for multiple machines associated with the authenticated - user. - - - 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_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 @@ -8741,6 +8977,38 @@ 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_claim: + type: number + description: Host reliability claim. Values above 0 mean + SLA is enabled on the ask. + sla_sigma_x: + type: number + description: SLA confidence spread around the claim. + sla_max_beta: + type: number + description: "Optional cap on client-derived \u03B2 for\ + \ this ask (support-directed). Hosts do not\nset \u03B2\ + ; leave unset for uncapped.\n" + example: + machines: + - id: '12345' + name: my-h100 + price_gpu: 3.5 + end_date: 1735689600 + min_chunk: 1 + sla_r_claim: 0.99 + sla_sigma_x: 0.5 '401': description: Unauthorized - User authentication failed '429': @@ -8989,6 +9257,229 @@ paths: tags: - Accounts operationId: showUser + /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 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: + - 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: 0.9999 + 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: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + exclusiveMaximum: true + maximum: 1 + default: 0.6667 + 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: + 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 + exclusiveMinimum: true + maximum: 1 + 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: "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 + 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 + 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 + - 'null' + format: float + 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: + 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 /api/v0/deployment/{id}/start: post: summary: start deployment diff --git a/api-reference/openapi/yaml/create_instance.yaml b/api-reference/openapi/yaml/create_instance.yaml index 9bfbbea2..7db5e9ee 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 --image [options]` (no `target_reliability` flag today) security: - BearerAuth: [] tags: @@ -61,8 +63,21 @@ paths: disk: type: number format: float + minimum: 8 + description: | + Size of local disk partition (in GB). Minimum 8 when specified. + target_reliability: + type: number + format: float + minimum: 0 + exclusiveMaximum: true description: | - Size of local disk partition (in GB) + 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: | @@ -162,6 +177,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 @@ -179,7 +196,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: @@ -323,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 diff --git a/api-reference/openapi/yaml/list_machine.yaml b/api-reference/openapi/yaml/list_machine.yaml index 9b35c946..52d59d7d 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 and 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_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: - BearerAuth: [] requestBody: @@ -61,6 +63,39 @@ paths: type: number format: float description: Maximum discount rate allowed for prepaid credits + sla_r_claim: + type: number + format: float + minimum: 0 + maximum: 0.9999 + 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 on new rentals. + 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 when enabling SLA. + sla_max_beta: + type: number + format: float + description: | + 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 + 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; ignored on asks. responses: '200': description: Successful response @@ -71,15 +106,43 @@ 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_claim: 0.99 + sla_sigma_x: 0.5 + results: + - machine_id: 12345 + user_id: 67890 + extended: 1 + new_contracts: [] + upd_contracts: [1] '400': description: Bad Request content: @@ -89,12 +152,32 @@ paths: properties: error: type: string - example: invalid_args + enum: + - invalid_args + - invalid_sla_params + - sla_not_approved + - sla_daemon_outdated + example: invalid_sla_params + msg: + type: string + example: No such machine(s) for your account + '401': + 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: Invalid machine id or parameters + example: Your key lacks the machine_write permission group '403': - description: Forbidden + description: Forbidden — machine locked content: application/json: schema: @@ -102,10 +185,12 @@ paths: properties: error: type: string - example: not_authorized + enum: + - machine_locked + example: machine_locked msg: type: string - example: Only machine owner can create ask contracts + example: Machine is decommissioned or migration-locked tags: - Machines components: diff --git a/api-reference/openapi/yaml/schedule_maint.yaml b/api-reference/openapi/yaml/schedule_maint.yaml index d8deafed..447ab2c6 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. @@ -128,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/search_offers.yaml b/api-reference/openapi/yaml/search_offers.yaml index fbf7ecdb..ea2b6f91 100644 --- a/api-reference/openapi/yaml/search_offers.yaml +++ b/api-reference/openapi/yaml/search_offers.yaml @@ -88,7 +88,25 @@ 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. 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: | + 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]}' @@ -266,7 +284,7 @@ paths: Default is 8GB. example: limit: 100 - type: on-demand + type: ondemand verified: eq: true rentable: @@ -362,7 +380,7 @@ paths: vram_costperhour: 0.009876 webpage: null vms_enabled: false - expected_reliability: 0.5 + expected_reliability: 0.99 is_vm_deverified: false resource_type: "gpu" cluster_id: null @@ -381,12 +399,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_earnings.yaml b/api-reference/openapi/yaml/show_earnings.yaml index 97183ba3..2bee32a4 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`. + CLI Usage: `vastai show earnings [options]` security: - BearerAuth: [] @@ -28,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: @@ -63,6 +69,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 +116,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 +134,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 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_instances.yaml b/api-reference/openapi/yaml/show_instances.yaml index fdc28df8..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 @@ -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. + 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: '{}' @@ -332,7 +334,26 @@ 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 dlperf: type: number nullable: true @@ -381,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/api-reference/openapi/yaml/show_machines.yaml b/api-reference/openapi/yaml/show_machines.yaml index 4e5c4420..d0d56e5e 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_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,35 @@ 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_claim: + type: number + description: Host reliability claim. Values above 0 mean SLA is enabled on the ask. + sla_sigma_x: + type: number + description: SLA confidence spread around the claim. + sla_max_beta: + type: number + description: | + Optional cap on client-derived β for this ask (support-directed). Hosts do not + set β; leave unset for uncapped. + example: + machines: + - id: "12345" + name: my-h100 + price_gpu: 3.5 + end_date: 1735689600 + min_chunk: 1 + sla_r_claim: 0.99 + sla_sigma_x: 0.5 '401': description: Unauthorized - User authentication failed '429': diff --git a/api-reference/openapi/yaml/sla_backtest.yaml b/api-reference/openapi/yaml/sla_backtest.yaml new file mode 100644 index 00000000..542434a6 --- /dev/null +++ b/api-reference/openapi/yaml/sla_backtest.yaml @@ -0,0 +1,227 @@ +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 + 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. 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: + - 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: 0.9999 + 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: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + exclusiveMaximum: true + maximum: 1 + default: 0.6667 + 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: + 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 + exclusiveMinimum: true + maximum: 1 + 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: | + 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 + 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 + 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: + 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..24a21a7e 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) — 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 @@ -207,6 +208,25 @@ 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):** Create via [Create API Key](/api-reference/accounts/create-api-key). See [Creating Scoped Keys](#creating-scoped-keys) for the required `api` wrapper. + +```json +{ + "api": { + "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) @@ -220,6 +240,20 @@ Below is the complete mapping of which endpoints each permission category contro - [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/create-instance.mdx b/cli/reference/create-instance.mdx index faf04d2b..e71bbe2c 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 @@ -14,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 @@ -129,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`. @@ -143,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 diff --git a/cli/reference/search-offers.mdx b/cli/reference/search-offers.mdx index 598ea681..97fc9255 100644 --- a/cli/reference/search-offers.mdx +++ b/cli/reference/search-offers.mdx @@ -44,11 +44,11 @@ vastai search offers [--help] [--api-key API_KEY] [--raw] - New search exp + Experimental search path — not recommended for production use. Prefer the default search for SLA filtering. - + Maximum number of offers to return. Prefer an explicit limit when comparing SLA-inclusive `dph_total` results; combine with `--order` / `-o` as needed. @@ -77,10 +77,18 @@ 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' +# 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 vastai search offers 'compute_cap > 610 total_flops > 5 datacenter=True' @@ -88,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' @@ -134,7 +142,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 | @@ -144,7 +152,16 @@ 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 | 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/docs.json b/docs.json index 62a07bf6..06c0f7e8 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" @@ -599,6 +600,8 @@ "icon": "lightbulb", "pages": [ "host/hosting-overview", + "host/sla-offers", + "host/sla-backtester", "host/understanding-verification", "host/earning" ] @@ -824,7 +827,7 @@ "links": [ { "label": "FAQ", - "href": "/guides/reference/faq" + "href": "https://docs.vast.ai/guides/reference/faq" }, { "label": "Discord", diff --git a/guides/instances/choosing/find-and-rent.mdx b/guides/instances/choosing/find-and-rent.mdx index 6db382bb..4e8298ee 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 @@ -54,16 +54,19 @@ 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%. - Rental Option: RENT Button +- 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):** 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 -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 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) @@ -71,7 +74,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) @@ -80,6 +83,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..1efdb0b3 --- /dev/null +++ b/guides/instances/choosing/sla-coverage.mdx @@ -0,0 +1,319 @@ +--- +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 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.** 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 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 + +| 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 | **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). **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). + + + +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 + +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: + +- 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. + +SLA is most useful for **long-running production workloads** where unexpected downtime has a real cost beyond the hourly rate. + +## How pricing works + +Quoted hourly cost with SLA in search (`dph_total`): + +``` +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 | +| 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%. 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 + +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 | +| Storage (at search allocation) | ~$0.01/hr | +| SLA charge | ~$0.008/hr | +| **Total (`dph_total`)** | ~$3.52/hr | + +## 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 + +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 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. + +CLI and API examples below use the same filters. + +### Search filters + +| 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` | + + +**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 +# 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) | +| `dph_total` | Total hourly cost **including** the SLA charge | +| `expected_reliability` | Host's reliability claim | + +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 may not apply to the displayed total. Confirm in the console price breakdown. SLA charges are never discounted. + + +### Comparing offers + +| Offer | GPU/hr | Host claim | Your target | SLA charge/hr | +| --- | --- | --- | --- | --- | +| 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. Sort by `dph_total` to compare total quoted cost. + +### API automation + +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 +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", + "verified": {"eq": true}, + "rentable": {"eq": true}, + "allocated_storage": 50, + "order": [["dph_total", "asc"]], + "target_reliability": {"eq": 0.95}, + "has_sla": {"eq": true}, + "expected_reliability": {"gte": 0.99} + }' +``` + +**2. Rent** the chosen offer ID and pass the **same** target: + +```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). + +**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`. 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 | +| --- | --- | --- | +| 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 | +| 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 (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 | + +**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 + +When you rent an SLA-backed offer **with a target set**: + +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. + +### What you pay during an 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. + + +**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 + +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 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) + +Using the H100 example ($84/day compute, ~$0.20/day SLA charge, target 95%, host claim 99%): + +| Scenario | Approx. SLA charge | Approx. settlement credit | Net vs no SLA (approx.) | +| --- | --- | --- | --- | +| 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. + +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. + + +### 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. + +## 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 + +### In the web console + +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. + +### API integrators + +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 + +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. + +| 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` 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 + +- **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. + +## 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 (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? + +**Console:** After UTC settlement, open **Account → Billing** and look for SLA credit line items alongside compute charges. + +**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 + +- [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 5589bdf8..a322f43b 100644 --- a/host/hosting-overview.mdx +++ b/host/hosting-overview.mdx @@ -1,12 +1,14 @@ --- 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" --- + +**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. @@ -16,7 +18,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. @@ -38,15 +40,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). 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: -- 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 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 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. @@ -58,7 +61,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: @@ -106,7 +109,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 @@ -124,11 +127,11 @@ 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) -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. @@ -140,15 +143,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 @@ -167,7 +170,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: @@ -194,11 +197,11 @@ 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 +### 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) @@ -210,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' @@ -218,23 +221,41 @@ 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' +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. + + +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. ## 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. +**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 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. +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. -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. +Use these paths in order: -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. +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. + +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 @@ -244,23 +265,28 @@ 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? 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? / Why is my machine not listed? + +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 +- 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'`. ### 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 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? @@ -272,11 +298,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). - -### 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). +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). ### Can I send a message to a client using my machine letting them know that I fixed an issue that they were having? @@ -284,7 +306,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. 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? @@ -292,11 +314,13 @@ 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? -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? @@ -305,11 +329,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 new file mode 100644 index 00000000..eac84b9c --- /dev/null +++ b/host/sla-backtester.mdx @@ -0,0 +1,330 @@ +--- +title: "SLA Earnings Backtester" +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 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 SLA charges — you do not need this API. + +**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 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. + + +**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 + +| 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. 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 rental activity. + +Use the backtester to: + +- 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) + +For how SLA offers work once listed, see [SLA Offers](/host/sla-offers). + +## How it works + +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 **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 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 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` (weights recent vs longer-term uptime in settlement). Hosts cannot set β via the listing API. + + +## Before you start + +**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 request in [Example request](#example-request) 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/ +``` + +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. + +### Query parameters + +| Parameter | Required | Description | +| --- | --- | --- | +| `machine_id` | Yes | ID of your machine | +| `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 | Not user-configurable — the API derives timescale weighting from `r`. | + +### Limits + +| Limit | Value | +| --- | --- | +| 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 + +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 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" +``` + +Compare two confidence levels on the same history: + +```bash +# 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.6667" + +# 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" +``` + +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.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 +{ + "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, + "beta": 0.5 + }, + "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, + "reserve": 0.0 + } +} +``` + +### Top-level fields + +| 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. 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`) | +| `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`) + +| 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 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. + +### 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 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 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 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 — 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 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 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. + + +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` | Tight | `sla_sigma_x ≈ 0.2` | +| `0.6667` | Normal (default) | `sla_sigma_x ≈ 0.5` | +| `0.50` | Wide | `sla_sigma_x ≈ 1.0` | + +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 + +| HTTP | `error` / shape | Cause | +| --- | --- | --- | +| 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). | + +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: + - 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 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 + +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" +``` + +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): + +```bash +for id in $(vastai show machines -q); do + 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 + 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 2 +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` / `sla_sigma_x` 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 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 new file mode 100644 index 00000000..78c1e9aa --- /dev/null +++ b/host/sla-offers.mdx @@ -0,0 +1,623 @@ +--- +title: "SLA Offers" +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 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 set, how clients choose coverage, and what happens when uptime is good or bad. + + +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 [SLA Coverage](/guides/instances/choosing/sla-coverage) for how SLA appears in search and billing. + + +## 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). 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) | + +## 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 + + +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):** + +- 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 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. + +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). + + +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. 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. +- **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 host knobs only: + +- **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). + +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 two host ideas plus one client choice: + +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. + +When a client rents an on-demand instance on your SLA-listed offer with a chosen target: + +- 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). + +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. + +### How reliability 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. + +- **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. 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 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. | + +### Advanced: `sla_max_beta` (optional) + +**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 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). + + + +| Concept | Console | Listing API | Backtester | Client sees / sets | +| --- | --- | --- | --- | --- | +| 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 is not an uptime target.** It controls how aggressively SLA charges are priced around your claim. + + +### Machine reliability score vs SLA reliability + +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`: + +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 **claim** at a level you can sustain; clients who pick targets below your claim see lower SLA charges. + +### Confidence values + +**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. + +| Console label | API `sla_sigma_x` | Backtester `p` | Pricing effect | +| --- | --- | --- | --- | +| 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). + +**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 + +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. 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`. + + +### 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 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. + +### 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_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 + +### Web console + +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**. 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. + +#### Updating SLA on an already-listed machine + +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 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. + + +#### Web console SLA preview + +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) + +New hosts: use the web console steps above first. Use the API when you need scripting, partial updates, or fleet automation. + + +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 + +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`**. +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. 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). + + +```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, + "price_gpu": 3.50, + "sla_r_claim": 0.99, + "sla_sigma_x": 0.5, + "end_date": 1893456000 + }' +``` + +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). + + +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 +{ + "machine": 12345, + "price_gpu": 3.50, + "end_date": 1893456000, + "sla_r_claim": 0.99, + "sla_sigma_x": 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_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`: + +```bash +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. + +Then `PUT /api/v0/machines/create_asks/` with merged fields. + + +### Fleet listing workflow (advanced — fleet operators only) + +`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. 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 + 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 + # 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_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" \ + -d "$body") + echo "machine_id=$id response: $resp" + sleep 2 +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. 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: + +```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_claim": 0.995, "sla_sigma_x": 0.2}' +``` + +**Disable SLA on new rentals** — set `sla_r_claim` to `0` (active contracts keep their terms). + +#### Common errors + +| Status | Code / shape | When it happens | +| --- | --- | --- | +| 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 | +| 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. + +**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 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 charge (client pays) | ~**$0.008/hr** (~$0.20/day at 24 hr) | + +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. + +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 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. + + +### Search / client-visible fields + +When SLA is enabled on an offer, clients see: + +- **`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 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 has_sla=true target_reliability=0.95' --raw \ + | jq '[.offers[] | select(.is_bid == false) | {id, num_gpus, dph_total, expected_reliability, reliability}]' +``` + +### If reliability is strong relative to the client's target + +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 reliability (simplified) | You net (per day) | +| --- | --- | +| ~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 SLA charge. + +### What if measured reliability is between the client's target and my claim? + +Example: you publish **claim 99%**, the client chose **target 95%**, and measured reliability is **~97%**. + +- **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 your belief/pricing knob; the client's **target** is what drives payout eligibility. + +### If the client's target is missed + + +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. + + +These scenarios show settlement when reliability **drops to or below** a 95% client target — they are boundary illustrations, not typical strong days: + +| Measured reliability (simplified) | You net (per day) | +| --- | --- | +| 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 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. + +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% and deliver 99.5% + +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 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. + +### Clients target near your claim + +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 reliability history is volatile or the machine is new. + +### 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` 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. 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) +# 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). + +**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. + + +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 + +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 claim and `sla_sigma_x` against [validation rules](#validation-rules). +- **`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. + +## Monitoring SLA after listing + +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 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 (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 + +**Linux (GNU date):** + +```bash +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 -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. + +**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}' +``` + +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) + + +**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` | + +`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 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=`. + +**Quick rules:** +- **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 +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}' +``` + + +**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=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 | Strong day (meet client target) | Weak day (miss client target) | +| --- | --- | --- | +| `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`). +- Settlement is evaluated on UTC day boundaries. Rows typically update within a few hours after UTC midnight. + +## Tips for competitive SLA offers + +- **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/sdk/python/reference/create-instance.mdx b/sdk/python/reference/create-instance.mdx index cd9ab581..379c8e88 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 @@ -37,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 1c385fd7..863b1404 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 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 ```bash @@ -11,7 +15,7 @@ vastai list machine ID [options] ## Arguments - id of machine to list + ID of the machine to list. ## Options @@ -63,15 +67,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 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. -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 196ca1ba..e4dbddc9 100644 --- a/snippets/host/cli/schedule-maint.mdx +++ b/snippets/host/cli/schedule-maint.mdx @@ -1,45 +1,73 @@ -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 ```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`. 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 - 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. - 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`). (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 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. + +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 +# 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 \ + --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. Use the current UTC epoch for `--sdate` and an integer `--duration` (hours): + +```bash +vastai schedule maint MACHINE_ID --sdate "$(date -u +%s)" --duration 1 --maintenance_category power +``` -Example: vastai schedule maint 8207 `--sdate` 1677562671 `--duration` 0.5 `--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. ## Examples ```bash -vastai schedule maint +vastai schedule maint --sdate --duration --maintenance_category software ``` ## Global Options diff --git a/snippets/host/sdk/list-machine.mdx b/snippets/host/sdk/list-machine.mdx index a67e8bef..583ab8e8 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 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 ```python @@ -13,42 +17,42 @@ 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, ) -> 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 + Offer expiration (Unix timestamp or MM/DD/YYYY). ## Returns @@ -61,6 +65,8 @@ VastAI.list_machine( from vastai import VastAI client = VastAI(api_key="YOUR_API_KEY") -result = client.list_machine(id=12345) +# 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) ```