---
title: "Stop Runner"
method: POST
path: "/serverless/runners/{runner_id}/stop"
tags: ["Serverless", "Runners"]
---

# Stop Runner

`POST /serverless/runners/{runner_id}/stop`

## Request

- Base URL: `https://api.fal.ai/v1`
- URL: `https://api.fal.ai/v1/serverless/runners/{runner_id}/stop`
- Auth: API key in header `Authorization`

Gracefully stops a serverless runner owned by the authenticated account.
The runner stops accepting new requests and finishes in-flight work before shutting down.

Set `replace_first=true` to start a replacement before stopping this runner.
This option applies to deployed application runners, not standalone `fal run` runners.

A successful response acknowledges the stop request; the runner may still be draining.
Stopping a runner does not change the application's scaling configuration, so autoscaling may start new runners.

**Required permissions:** `serverless:runners:terminate`. Key presets that include them: `COMPUTE`, `FULL`. See [key permissions](https://fal.ai/docs/documentation/model-apis/authentication/key-based#permissions).

## Path parameters

- `runner_id` string, required: ID of the serverless runner to stop

## Query parameters

- `replace_first` 'true' | 'false': Whether to start a replacement runner before stopping this one. Defaults to false.

## Response `200`

Graceful stop requested successfully

- object
  - `runner_id` string, required: ID of the runner whose graceful stop was requested

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `429`: Rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-10-28** `3b3b61bedf06`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fal/apis/platform-apis/changes/serverless/runners/:runner_id/stop/post.md)

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) - [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/fal/apis/platform-apis/revisions/3b3b61bedf06?raw)