---
title: "Fetch a file into a VM from a presigned URL"
method: POST
path: "/v1/vms/{id}/files/fetch"
tags: ["files"]
---

# Fetch a file into a VM from a presigned URL

`POST /v1/vms/{id}/files/fetch`

Pulls `url` into the guest at `path`. `url` must be a presigned
storage URL previously minted by `POST /v1/vms/{id}/files/presign`
(URLs from other sources are rejected).

Response mirrors `/v1/vms/{id}/exec`: reports stdout/stderr/exit
code of the underlying download+unpack operation.

Not idempotent; not retried by default.

## Request body

- FileFetchRequest
  - `url` string, uri, required — Must be the `downloadUrl` previously returned by `POST /v1/vms/{id}/files/presign` (URLs from other sources are rejected).
  - `path` string, required — Absolute destination path inside the guest filesystem.
  - `timeoutSec` integer — Per-fetch timeout in seconds.

## Response `200`

Fetch completed (command result)

- ExecVMResponse — Buffered response shape for `POST /v1/vms/{id}/exec` under `Accept: application/json`. The server collects the streamed events and returns this aggregate once the command exits. Per-stream output is capped at 4 MiB; overflow bytes are dropped and signalled via `stdoutTruncated` / `stderrTruncated`. Streaming clients (`Accept: application/x-ndjson`) receive every byte without a cap.
  - `exitCode` integer, required
  - `stdout` string, required
  - `stderr` string, required
  - `timedOut` boolean, required
  - `stdoutTruncated` boolean, required — True if the collector dropped stdout bytes past the 4 MiB cap.
  - `stderrTruncated` boolean, required — True if the collector dropped stderr bytes past the 4 MiB cap.
  - `durationMs` integer, required

## Other responses

- `400` — Invalid request
- `401` — Missing or invalid credentials
- `404` — Resource not found
- `409` — VM is not running
- `413` — Object too large for VM disk / insufficient guest disk space
- `500` — Internal server error
- `502` — Failed to HEAD the presigned URL

## Changes

- **2026-04-22** `fdb53b5a79b3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fastvm-org/apis/fastvm-api/changes/v1/vms/:id/files/fetch/post.md)

---

[API](https://skmtc.dev/fastvm-org/apis/fastvm-api.md) · [All operations](https://skmtc.dev/fastvm-org/apis/fastvm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fastvm-org/fastvm-api/revisions/480d9714a7a5/schema)