---
title: "Run command"
method: POST
path: "/v1/replica/{id}/exec"
tags: ["Commands and terminals"]
---

# Run command

`POST /v1/replica/{id}/exec`

## Request

- Base URL: `https://api.replicas.dev`
- URL: `https://api.replicas.dev/v1/replica/{id}/exec`
- Auth: HTTP bearer

Runs a shell command and returns its output and exit code. Commands that outlast `timeout_seconds` are stopped and return `timed_out: true`. Use a terminal session for interactive or long-running work. The replica must be active.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Replicas-Api-Version` '2026-10-07'

## Request body

- ExecRequest
  - `command` string, required: Shell command, run in the workspace root
  - `timeout_seconds` integer

## Response `200`

Success

- ExecResponse
  - `output` string, required: Combined stdout and stderr, last 64 KB
  - `exit_code` integer, nullable, required: `null` when the command timed out
  - `timed_out` boolean, required
  - `truncated` boolean, required

## Other responses

- `400`: Bad request - Missing or invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `404`: Resource not found
- `409`: Conflict - Resource already exists or operation conflicts with current state
- `500`: Internal server error

---

[API](https://skmtc.dev/replicas/apis/replicas-api.md) - [All operations](https://skmtc.dev/replicas/apis/replicas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replicas/apis/replicas-api/revisions/2703ac1c9cb7?raw)