---
title: "Read a single file"
method: POST
path: "/operations/getfile"
tags: ["operations"]
---

# Read a single file

`POST /operations/getfile`

## Request

- Base URL: `http://localhost:5572`
- URL: `http://localhost:5572/operations/getfile`
- Auth: one of:
  - HTTP basic
  - none
- TypeScript: <https://skmtc.dev/rclone/apis/rclone-rc-api/docs/operations/getfile/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns the contents of one file in the JSON response. It reads at most 2 MiB, so use `offset` and `count`, `head` or `tail` to read part of a larger file. Only one of those three forms can be used in a call. To stream whole files, use rclone's file serving with `--rc-serve` instead.

## Headers

- `Prefer` 'respond-async'

## Request body

- object
  - `_config` object: Config overrides for this call only.
  - `_filter` object: Filter overrides for this call only.
  - `_group` string: Stats group for this call.
  - `fs` string, required: Remote name or path of the file, for example `drive:path/to/file`. It can also be a directory, with the file named in `remote`.
  - `remote` string: Path to the file within `fs`, for example `file.txt`.
  - `offset` integer: Byte offset to start reading at. A negative value counts from the end of the file. Defaults to 0.
  - `count` integer: Number of bytes to read. Defaults to -1, which reads to the end of the file.
  - `head` integer: Read only the first N bytes.
  - `tail` integer: Read only the last N bytes.
  - `maxSize` integer: Largest number of bytes the call may return. It can only lower the built-in limit of 2097152 bytes (2 MiB).
  - `base64` boolean: Set to true to return the contents base64 encoded. Binary files need this, because the call fails when the contents aren't valid UTF-8.

## Response `200`

Contents of the file from `operations/getfile`.

- object
  - `result` string, required: Contents of the file, as text or as a base64 encoded string when `base64` is set.

## Other responses

- `202`: The call is running in the background, because the request sent `Prefer: respond-async`. Poll `job/status` with the job ID. A job can be queried for up to 1 minute after it finishes.
- `401`: Missing or wrong credentials. The auth layer sends this as plain text, before rclone's JSON errors apply.
- `4XX`: Any error response (HTTP 4xx/5xx)
- `5XX`: Any error response (HTTP 4xx/5xx)

## Changes

- **2026-11-11** `a7af46c0c706`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rclone/apis/rclone-rc-api/changes/operations/getfile/post.md)

---

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