> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reserved TPM

> Reserve guaranteed serverless inference capacity in advance, for no extra charge

> [!NOTE]
>
> Reserved TPM is in Beta and available to select pilot customers. To join the
> waitlist, send us a note from the support form in your [Sail
> dashboard](https://app.sailresearch.com) (recommended), or [contact
> support](https://www.sailresearch.com/support).

With Reserved TPM, you can reserve guaranteed serverless inference capacity
ahead of time on your selected model and service tier.

You **prepay a [reservation deposit](#billing) at your normal pay-per-token
pricing in exchange for provisioned throughput**, measured in **uncached input
and output tokens per minute** (TPM). Reserved TPM also **removes the
[queueing time](https://docs.sailresearch.com/service-tiers.md#service-tier-comparison) associated with
Balanced and Flex altogether.**

Reserved TPM is fully self-serve and available on Pro and Enterprise plans.

## When to use Reserved TPM

* You expect a period of heavy traffic and need guaranteed capacity at a
  specific time, with as little as one hour's notice.
* You want guaranteed capacity on demand, with the same serverless APIs and
  pay-per-token pricing, without renting or managing dedicated servers.
* You want to run at Balanced or Flex [TPS targets](https://docs.sailresearch.com/service-tiers.md#service-tier-comparison),
  with reserved capacity that removes their usual
  [queueing time](https://docs.sailresearch.com/service-tiers.md#service-tier-comparison).

## How it works

* You can book Reserved TPM for a start time at least one hour in advance.
  You will specify:
  * The **model and service tier**
    * *Optional*: The **LoRA name or ID**, if reserving throughput for your LoRA
      fine-tuned model (note - you must [upload your LoRA to Sail](https://docs.sailresearch.com/loras.md)
      first).
  * The **duration of the reservation** in hours, from 1 hour to 3 days long
  * The **reservation start time**, from 1 hour to 7 days in advance
  * The **uncached input TPM** amount to reserve
  * The **output TPM** amount to reserve
* **Eligible inference requests during your reservation are covered by an SLA
  guaranteeing the uncached input TPM and output TPM you reserved.**

## Billing

When you book, Sail charges a **reservation deposit** based on your reserved
uncached input and output TPM, multiplied by the duration in minutes, at your
normal [pay-per-token pricing](https://docs.sailresearch.com/pricing.md). There is no surcharge for Reserved TPM. The
deposit is nonrefundable except under the
[free cancellation policy](#cancel-a-reservation).

**All eligible inference usage during your reservation draws from the deposit
first**. **This includes cached input tokens**, even though only your projected
*uncached* input and output tokens determine the deposit amount.

**Your deposit balance and your TPM allowances are separate:**

* The deposit is a monetary balance shared across the reservation. Once it's
  exhausted, eligible usage draws from your general credit balance on Pro or
  is billed to your invoice on Enterprise.
* Your reserved uncached input and output TPM allowances renew each minute
  and do not roll over to the next minute. Eligible requests within these
  allowances keep the Reserved TPM SLA until the
  reservation ends, even after the deposit runs out. Sail serves requests
  above these allowances when capacity is available, without the Reserved
  TPM SLA.

On Pro, Sail deducts the deposit from your credit balance when you book.
On Enterprise, Sail bills the deposit on your invoice.

### Reserved TPM cost calculator

> [accordion] Estimate your deposit and total cost
>
> The cost calculator requires JavaScript. See [Pricing](https://docs.sailresearch.com/pricing.md) for each
> model's pay-per-token pricing.

## Book and use Reserved TPM

Send `POST /v1/reserved-tpm` with an `Idempotency-Key` header:

> [tab] Base model
>
> ```python Python theme={null}
> from datetime import datetime, timezone
>
> import sail
>
> reservation = sail.ReservedTpm.create(
>     model="deepseek/deepseek-v4-pro-0813",
>     service_tier="flex",
>     starts_at=datetime(2026, 11, 20, 16, tzinfo=timezone.utc),
>     duration_hours=4,
>     uncached_input_tpm=1_000_000,
>     output_tpm=200_000,
> )
>
> print(reservation.id, reservation.status)
> ```
>
> ```typescript TypeScript theme={null}
> import { ReservedTpm } from "@sailresearch/sdk";
>
> const reservation = await ReservedTpm.create({
>   model: "deepseek/deepseek-v4-pro-0813",
>   serviceTier: "flex",
>   startsAt: new Date("2026-11-20T16:00:00Z"),
>   durationHours: 4,
>   uncachedInputTpm: 1_000_000,
>   outputTpm: 200_000,
> });
>
> console.log(reservation.id, reservation.status);
> ```
>
> ```bash cURL theme={null}
> curl https://api.sailresearch.com/v1/reserved-tpm \
>   -H "Authorization: Bearer $SAIL_API_KEY" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: 9a8b1fc3-b9da-4b14-bb9b-98978c814b2d" \
>   -d '{
>     "model": "deepseek/deepseek-v4-pro-0813",
>     "service_tier": "flex",
>     "starts_at": "2026-11-20T16:00:00Z",
>     "duration_hours": 4,
>     "uncached_input_tpm": 1000000,
>     "output_tpm": 200000
>   }'
> ```

> [tab] LoRA fine-tune
>
> ```python Python theme={null}
> from datetime import datetime, timezone
>
> import sail
>
> reservation = sail.ReservedTpm.create(
>     model="zai-org/GLM-5.3",
>     service_tier="flex",
>     lora="funnier-v1",
>     starts_at=datetime(2026, 11, 20, 16, tzinfo=timezone.utc),
>     duration_hours=4,
>     uncached_input_tpm=1_000_000,
>     output_tpm=200_000,
> )
>
> print(reservation.id, reservation.status)
> ```
>
> ```typescript TypeScript theme={null}
> import { ReservedTpm } from "@sailresearch/sdk";
>
> const reservation = await ReservedTpm.create({
>   model: "zai-org/GLM-5.3",
>   serviceTier: "flex",
>   lora: "funnier-v1",
>   startsAt: new Date("2026-11-20T16:00:00Z"),
>   durationHours: 4,
>   uncachedInputTpm: 1_000_000,
>   outputTpm: 200_000,
> });
>
> console.log(reservation.id, reservation.status);
> ```
>
> ```bash cURL theme={null}
> curl https://api.sailresearch.com/v1/reserved-tpm \
>   -H "Authorization: Bearer $SAIL_API_KEY" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: 4f2c8e1a-7b3d-4e9f-a6c5-2d8b1e0f9a73" \
>   -d '{
>     "model": "zai-org/GLM-5.3",
>     "service_tier": "flex",
>     "lora": "funnier-v1",
>     "starts_at": "2026-11-20T16:00:00Z",
>     "duration_hours": 4,
>     "uncached_input_tpm": 1000000,
>     "output_tpm": 200000
>   }'
> ```

> [accordion] Reservation fields
>
> | Field | Description |
> | - | - |
> | `model` | The model to reserve. |
> | `service_tier` | `asap`, `balanced`, or `flex`. |
> | `lora` | Optional. The name or ID of a [LoRA](https://docs.sailresearch.com/loras.md) on the model. The reservation then covers requests that use that LoRA. |
> | `starts_at` | When the reservation starts, as an RFC 3339 time. |
> | `duration_hours` | Whole hours, from 1 to 72. |
> | `uncached_input_tpm` | Uncached input tokens per minute. |
> | `output_tpm` | Output tokens per minute. |
> | `routing.allowed_countries` | Optional. Set `["US"]` for a [US-only](https://docs.sailresearch.com/us-only-inference.md) reservation. |

Retrying with the same `Idempotency-Key` will return the same reservation.
Reusing a key with different fields will return HTTP `409`.

### Errors

> [accordion] HTTP status codes and errors
>
> | Status | Code | Meaning |
> | - | - | - |
> | `400` | `reservation_below_minimum` | The reservation is below the size required to use Reserved TPM for the model and service tier requested. |
> | `400` | `model_not_available` | The model is not yet available via Reserved TPM. |
> | `400` | `service_tier_not_available` | The model at the selected service tier is not yet available via Reserved TPM. |
> | `400` | `us_only_not_available` | The model at the selected service tier is not yet available for US-only reservations. |
> | `402` | `credits_exhausted` | Your Sail credit balance isn't above the price. Add credits and book again. This is only applicable to non-enterprise organizations. |
> | `409` | `capacity_unavailable` | The window you've requested is fully booked. `earliest_start` is the earliest start available for the reservation, or `null`. |
> | `409` | `idempotency_key_reused` | The `Idempotency-Key` was already used with different fields. |

### Success

If the Reserved TPM you've requested is available, Sail books the reservation
and charges the [deposit](#billing). The response contains the
[reservation](#reservation-details).

### Use a reservation

Your inference requests need no changes. While your reservation is active,
requests on the matching model and service tier automatically use your
reserved capacity.

Using Reserved TPM has the added benefit of removing the [request queueing
latency](https://docs.sailresearch.com/service-tiers.md#service-tier-comparison) that would otherwise be
incurred on the Balanced and Flex [service tiers](https://docs.sailresearch.com/service-tiers.md).

* [Responses API](https://docs.sailresearch.com/api-reference/responses-api/create-a-response.md)
* [Chat Completions API](https://docs.sailresearch.com/api-reference/chat-completions-api/create-a-chat-completion.md)
* [Messages API](https://docs.sailresearch.com/api-reference/messages-api/create-an-anthropic-message.md)

> [!WARNING]
>
> Don't use the [Batch API](https://docs.sailresearch.com/api-reference/batches-api/create-a-batch.md) for
> Reserved TPM. Batch requests aren't eligible for Reserved TPM SLAs.

#### Track TPM allowances and SLA coverage

During your reservation, use the response headers on Responses, Chat Completions,
and Messages requests to see whether each request uses your reserved TPM or
runs as normal traffic.

`X-Sail-Reserved-Tpm-Coverage` reports:

* `covered`: The request uses your reservation and receives the Reserved TPM SLA.
* `excess`: The request doesn't fit within the remaining uncached input allowance,
  or the output allowance is already exhausted for this minute. Sail can still
  serve it when capacity is available, without the Reserved TPM SLA.

The remaining-token headers show your organization's combined TPM allowances
across active reservations on the same model and service tier. They report
reserved allowances only, not how much shared capacity is available to your
organization.

Uncached input counts when a request is admitted. Output counts shortly after
a covered request finishes, in the minute it finishes. Both allowances reset
at the start of each clock minute (UTC); unused allowances do not roll over.
This is not a rolling 60-second window.

You can also [get a reservation](#get-a-reservation) and read `current_minute`
to check its remaining allowances.

> [accordion] Response headers
>
> | Header | Value |
> | - | - |
> | `X-Sail-Reserved-Tpm-Coverage` | `covered` or `excess`, as described above. |
> | `X-Sail-Reserved-Tpm-Id` | The reservation used by the request. Only sent with `covered`. |
> | `X-Sail-Reserved-Tpm-Remaining-Uncached-Input-Tokens` | Uncached input tokens left this minute, after this request. |
> | `X-Sail-Reserved-Tpm-Remaining-Output-Tokens` | Output tokens left this minute. This request's own output isn't included yet. |
> | `X-Sail-Reserved-Tpm-Reset` | When the minute ends and both allowances reset, as an RFC 3339 time. |
>
> Only the response to the original request has the headers:
>
> * A retry with the same [idempotency key](https://docs.sailresearch.com/idempotency.md) doesn't return them.
> * Polling a background response with `GET /v1/responses/{id}` doesn't return
>   them.
> * If Sail can't count a request's tokens when it arrives, the response has no
>   headers, and the request runs as normal traffic.

> [!NOTE]
>
> **SLA coverage and billing are separate.** Both covered and excess usage on
> the reservation's model and service tier draw from its deposit first. To check
> the remaining deposit, [get the reservation](#get-a-reservation) and read
> `prepayment`.

### List reservations

List returns your organization's reservations, newest first, with `has_more`.
`limit` is 1 to 100 (default 20). To get the next page, pass the last ID as
`after_id`.

```python Python theme={null}
import sail

reservations = sail.ReservedTpm.list(limit=20)
```

```typescript TypeScript theme={null}
import { ReservedTpm } from "@sailresearch/sdk";

const reservations = await ReservedTpm.list({ limit: 20 });
```

```bash cURL theme={null}
curl "https://api.sailresearch.com/v1/reserved-tpm?limit=20" \
  -H "Authorization: Bearer $SAIL_API_KEY"
```

### Get a reservation

```python Python theme={null}
import sail

reservation = sail.ReservedTpm.get("rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47")
```

```typescript TypeScript theme={null}
import { ReservedTpm } from "@sailresearch/sdk";

const reservation = await ReservedTpm.get(
  "rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47",
);
```

```bash cURL theme={null}
curl https://api.sailresearch.com/v1/reserved-tpm/$RESERVATION_ID \
  -H "Authorization: Bearer $SAIL_API_KEY"
```

Getting a reservation also returns `current_minute`: how much of its uncached
input TPM and output TPM is left in the current minute, and when the minute
resets.

```json theme={null}
"current_minute": {
  "remaining_uncached_input_tokens": 750000,
  "remaining_output_tokens": 160000,
  "resets_at": "2026-11-20T17:31:00Z"
}
```

* `current_minute` is `null` when the reservation isn't running, or when Sail
  can't read the counts.
* A covered request's output counts shortly after it finishes, in the minute it
  finishes.
* If you have more than one reservation running on the same model and service
  tier, requests use up the one that ends first, then the next.
* Only getting a single reservation returns `current_minute`. Booking, listing
  and cancelling don't.

### Cancel a reservation

You can cancel a `booked` reservation to release the capacity, any time until
it ends. Finishing early does not refund any unspent deposit.

**Free cancel grace period:** you can cancel Reserved TPM **within 10 minutes
of booking** for a full refund of the deposit in Sail credits. Your organization
gets one free cancellation in a rolling 24-hour window.

Otherwise, **the deposit is nonrefundable**.

```python Python theme={null}
import sail

reservation = sail.ReservedTpm.get("rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47")
cancelled = reservation.cancel()

print(cancelled.status, cancelled.refund)
```

```typescript TypeScript theme={null}
import { ReservedTpm } from "@sailresearch/sdk";

const reservation = await ReservedTpm.get(
  "rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47",
);
const cancelled = await reservation.cancel();

console.log(cancelled.status, cancelled.refund);
```

```bash cURL theme={null}
curl -X POST https://api.sailresearch.com/v1/reserved-tpm/$RESERVATION_ID/cancel \
  -H "Authorization: Bearer $SAIL_API_KEY"
```

`free_cancel_until` shows when a free cancel stops being available, or `null`
when the reservation is not refundable. The response's `refund` contains
`amount_cents` and a `status` of `pending` until the credit is added, then
`refunded`. If nothing is refunded, `refund` is `null`.

### Reservation details

> [accordion] Reservation object, statuses, and usage
>
> A reservation looks like:
>
> ```json theme={null}
> {
>   "id": "rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47",
>   "object": "reserved_tpm",
>   "model": "deepseek/deepseek-v4-pro-0813",
>   "service_tier": "flex",
>   "lora": null,
>   "starts_at": "2026-11-20T16:00:00Z",
>   "ends_at": "2026-11-20T20:00:00Z",
>   "duration_hours": 4,
>   "uncached_input_tpm": 1000000,
>   "output_tpm": 200000,
>   "routing": null,
>   "price": { "amount_cents": 17712, "currency": "USD" },
>   "prepayment": {
>     "consumed_cents": 0,
>     "remaining_cents": 17712,
>     "as_of": null
>   },
>   "free_cancel_until": "2026-11-13T18:12:11Z",
>   "refund": null,
>   "status": "booked",
>   "created_at": "2026-11-13T18:02:11Z",
>   "updated_at": "2026-11-13T18:02:11Z",
>   "cancelled_at": null
> }
> ```
>
> | `status` | Meaning |
> | - | - |
> | `booked` | The reservation is confirmed. |
> | `pending_charge` | Payment is still processing. Get the reservation to check again. |
> | `charge_failed` | Payment failed. Nothing was charged and the capacity was released. |
> | `cancelled` | You cancelled the reservation. |
>
> `prepayment` shows how much of the reservation's deposit is used
> (`consumed_cents`) and left (`remaining_cents`), as of `as_of`. Note that
> updates to `prepayment` may continue for up to several hours past the end, because
> requests admitted near the end of the reservation can still draw from the
> deposit when they finish.

## FAQ

### Access and booking

> [accordion] Who can use Reserved TPM?
>
> Reserved TPM is currently in waitlisted Beta. Soon, this feature will be
> open to all users on Pro and Enterprise plans.

> [accordion] How do I get access?
>
> Reserved TPM is in Beta, by request. Send us a note from the support form in
> your [Sail dashboard](https://app.sailresearch.com), or [contact
> support](https://www.sailresearch.com/support).

> [accordion] How far ahead can I book Reserved TPM?
>
> From 1 hour to 7 days in advance. If you need to book further out, [contact
> support](https://www.sailresearch.com/support).

> [accordion] How long can a reservation be?
>
> From 1 hour to 3 days (72 hours), in whole hours.

> [accordion] What's the smallest reservation?
>
> Each model and service tier combination has a minimum reservation size, in
> dollars per hour.

> [accordion] Can I change a reservation?
>
> No, reservations can't be changed after booking. You must cancel and book
> another reservation instead.

> [accordion] Can I reserve TPM for a LoRA fine-tune?
>
> Yes. Book the LoRA's base model on Flex, with `lora` set to the LoRA's name
> or ID. That reservation covers requests that use that [LoRA](https://docs.sailresearch.com/loras.md). A
> reservation without `lora` covers only requests that don't use a LoRA.

### Usage and allowances

> [accordion] Can I see how much of a reservation I've used?
>
> Yes. [Get the reservation](#get-a-reservation): `prepayment` shows how much
> of its deposit is left, and `current_minute` shows how much of its
> uncached input and output TPM allowances remain this minute.

> [accordion] How can I tell whether a request used my reservation?
>
> Check the `X-Sail-Reserved-Tpm-Coverage` response header. `covered` means
> the request used your reservation and receives the Reserved TPM SLA;
> `excess` means it ran as normal traffic without that SLA. For a covered
> request, `X-Sail-Reserved-Tpm-Id` identifies the reservation it used. See
> [Track TPM allowances and SLA coverage](#track-tpm-allowances-and-sla-coverage)
> for the headers and when they're available.

> [accordion] Do the remaining TPM counts include shared capacity?
>
> No. The remaining-token headers and `current_minute` report only your
> remaining reserved allowances. A falling count means you've used some of
> this minute's allowance; it doesn't mean your reservation has become
> smaller. The allowances reset each minute.
>
> Requests above those allowances can still run as normal traffic when
> capacity is available, without the Reserved TPM SLA. These counts don't
> show how much additional shared capacity your organization can receive.

> [accordion] Does a reservation cover other service tiers?
>
> No. It covers only the reservation's designated model and tier. Requests on
> other tiers run as normal traffic.

> [accordion] How does a US-only reservation work?
>
> **A US-only reservation makes the requests it covers US-only.** They run in
> the US and are billed as US-only, matching the reservation's price, even
> without `routing.allowed_countries`. Still we recommend setting this on the
> individual requests as well in case usage exceeds your per-minute TPM
> allowances.

### Billing and cancellation

> [accordion] How does billing work?
>
> Sail charges a deposit when you book, and eligible usage draws from it
> first. See [Billing](#billing) for the calculation and how charges work on
> Pro and Enterprise.

> [accordion] Does the deposit carry across minutes?
>
> Yes, the deposit is available throughout the reservation, rather than
> divided into per-minute amounts.
>
> For example, with a \$100 deposit, eligible usage draws from that \$100
> until it's exhausted, regardless of when during the reservation you send
> the requests.
>
> Your uncached input and output TPM allowances renew each minute and do not
> roll over to the next minute. Sail serves requests above these allowances
> when capacity is available, without the Reserved TPM SLA.

> [accordion] What happens when usage exceeds the deposit during the reservation?
>
> Further usage draws from your general credit balance on Pro or is billed
> to your invoice on Enterprise. Eligible requests within your reserved
> uncached input and output TPM allowances keep the Reserved TPM SLA until
> the reservation ends. Exhausting the deposit doesn't reduce those
> allowances.

> [accordion] What if my org's credit balance runs out during a reservation?
>
> Eligible requests continue to run while the reservation has a remaining
> deposit. Other requests return `402` until you add credits.

> [accordion] What happens to the deposit I don't use?
>
> Any unspent deposit is nonrefundable. See [Billing](#billing).

> [accordion] What if my workload finishes early?
>
> You can optionally [**cancel your reservation**](#cancel-a-reservation)
> once your workload finishes to release the capacity. If you haven't used
> the full reservation deposit, the remaining amount is nonrefundable.

> [accordion] What happens if I cancel?
>
> Sail releases the capacity. Cancelling within 10 minutes of booking also
> refunds the full deposit as Sail credits, if you haven't already done such a
> cancellation in the past 24 hours. Any other cancellation is not eligible
> for a refund.
