> ## Documentation Index > Fetch the complete documentation index at: https://runcrate.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Reserve a running instance > Switches a running instance billed by the hour to a prepaid term of `term_months` that starts now, paid in full from credit. The price is the instance's own hourly rate less that length's discount, over the term's hours (730 a month). Hourly billing stops at the switch: the hours run so far are billed once, at the hourly rate, up to it. Send `expected_total_price` (that option's `total_price`): a different total is refused with 409 and `details.reason` `price_changed`, with the current `total_price`. An `Idempotency-Key` header is required: a retry with the same key returns the term already reserved (with the `Idempotent-Replayed: true` header) and charges nothing. Workspace owners and admins only, with an API key; an agent's sign-in is refused (a person reserves in the dashboard). Reserving 3 months or more, or taking the workspace's prepaid terms over $1,000, needs a verified identity (403). Refused with 402 without enough available credit (the balance less unbilled hourly use, this instance's included), when the environment's monthly budget has no room for the term, or while a payment on the workspace is disputed; and with 409 when the instance is not running, is already prepaid, is a job's machine, is being stopped, or the length is not offered. From then on it is a prepaid term like one bought at launch: it can't be stopped or terminated until it ends, its auto stop (`max_runtime_minutes`, `idle_shutdown_minutes`) is turned off, renewal opens 7 days before the end, and at the end the instance and its disk are deleted unless renewed. If the machine is lost, the unused time is returned as credit. ## OpenAPI ````yaml /api-reference/openapi.json post /instances/{id}/reserve openapi: 3.1.0 info: title: Runcrate API version: 1.0.0 summary: OpenAI-compatible inference API + GPU infrastructure API. description: >- Runcrate exposes two API surfaces. The inference API at `https://api.runcrate.ai/v1` is OpenAI-compatible: it accepts the standard OpenAI SDK with the base URL changed. The infrastructure API at `https://www.runcrate.ai/api/v1` manages GPU instances, jobs, persistent volumes, environments, SSH keys, templates, and billing. Both share a single `rc_live_*` API key. Pricing is per-token, per-image, per-second, or per-minute on the inference API (varies by model; see https://www.runcrate.ai/api/models/catalog for live rates) and per-second on GPU rentals (see https://www.runcrate.ai/pricing for hourly rates per GPU class). All infrastructure API responses are wrapped in `{ "data": ... }`. List responses also include a `meta` object with pagination cursors. Error responses use `{ "error": { "code": "...", "message": "..." } }`. termsOfService: https://www.runcrate.ai/terms contact: name: Runcrate url: https://www.runcrate.ai/contact license: name: Proprietary url: https://www.runcrate.ai/terms servers: - url: https://api.runcrate.ai/v1 description: Inference API (OpenAI-compatible) - url: https://www.runcrate.ai/api/v1 description: >- Infrastructure API (instances, jobs, storage, environments, ssh-keys, templates, billing) security: - ApiKeyAuth: [] tags: - name: Chat description: OpenAI-compatible chat completions. - name: Images description: Text-to-image generation. - name: Videos description: Async text-to-video and image-to-video generation. - name: Audio description: Text-to-speech and speech-to-text. - name: Embeddings description: Vector embeddings for RAG and search. - name: Models description: Model catalog discovery. - name: Instances description: GPU instance lifecycle. - name: Jobs description: >- Run one command on its own GPU machine. The machine stops, and billing ends, when the command exits. - name: Schedules description: >- Start an instance or a job later: once at a set time, or on a repeating cron schedule in your timezone. - name: Storage description: Persistent volume management. - name: Environments description: Resource isolation containers within a workspace. - name: Secrets description: >- Names of the secrets an environment's machines get. Values are set in the dashboard and never returned. - name: SSH Keys description: SSH key management for instance access. - name: Templates description: Pre-built instance images and configurations. - name: Billing description: Credit balance, transactions, usage metrics. paths: /instances/{id}/reserve: servers: - url: https://www.runcrate.ai/api/v1 post: tags: - Instances summary: Reserve a running instance description: >- Switches a running instance billed by the hour to a prepaid term of `term_months` that starts now, paid in full from credit. The price is the instance's own hourly rate less that length's discount, over the term's hours (730 a month). Hourly billing stops at the switch: the hours run so far are billed once, at the hourly rate, up to it. Send `expected_total_price` (that option's `total_price`): a different total is refused with 409 and `details.reason` `price_changed`, with the current `total_price`. An `Idempotency-Key` header is required: a retry with the same key returns the term already reserved (with the `Idempotent-Replayed: true` header) and charges nothing. Workspace owners and admins only, with an API key; an agent's sign-in is refused (a person reserves in the dashboard). Reserving 3 months or more, or taking the workspace's prepaid terms over $1,000, needs a verified identity (403). Refused with 402 without enough available credit (the balance less unbilled hourly use, this instance's included), when the environment's monthly budget has no room for the term, or while a payment on the workspace is disputed; and with 409 when the instance is not running, is already prepaid, is a job's machine, is being stopped, or the length is not offered. From then on it is a prepaid term like one bought at launch: it can't be stopped or terminated until it ends, its auto stop (`max_runtime_minutes`, `idle_shutdown_minutes`) is turned off, renewal opens 7 days before the end, and at the end the instance and its disk are deleted unless renewed. If the machine is lost, the unused time is returned as credit. operationId: reserveInstance parameters: - name: id in: path required: true schema: type: string - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 description: Unique per reserve, 1 to 255 visible ASCII characters. requestBody: required: true content: application/json: schema: type: object required: - term_months - expected_total_price properties: term_months: type: integer enum: - 1 - 3 - 6 - 12 description: One of `reserve_options.options`. expected_total_price: type: number description: >- The `total_price` of that length in `reserve_options.options`, in USD. responses: '200': description: The term, running from now. content: application/json: schema: type: object required: - data properties: data: type: object properties: subscription_id: type: string format: uuid term_months: type: integer enum: - 1 - 3 - 6 - 12 term_price_usd: type: number starts_at: type: string format: date-time ends_at: type: string format: date-time hourly_usage_settled_usd: type: number description: >- The hours run before the switch, billed at the hourly rate. 0 on a replay. cleared_max_runtime_minutes: type: integer nullable: true description: The max runtime that was turned off, or null. cleared_idle_shutdown_minutes: type: integer nullable: true description: The idle stop that was turned off, or null. '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' components: responses: BadRequest: description: Invalid request (missing fields, bad parameters). content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: >- Insufficient credits, the environment has reached its monthly budget (error code `BUDGET_REACHED`), or launches are paused while a payment on the workspace is disputed (`PAYMENT_HOLD`). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Authenticated but not permitted for this resource. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Conflict with existing resource (e.g. duplicate name). content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- Machine-readable error code (e.g. `validation_error`, `unauthorized`, `not_found`, `insufficient_credits`, `rate_limited`, `internal_error`). message: type: string description: Human-readable error message. details: type: object additionalProperties: true description: Optional structured error context. securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Use a Runcrate API key with the `rc_live_*` prefix as the bearer token. Create one at https://www.runcrate.ai/dashboard/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.