---
title: "List Files"
method: GET
path: "/v0/inboxes/{inbox_id}/files"
tags: ["inboxes > files"]
---

# List Files

`GET /v0/inboxes/{inbox_id}/files`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/inboxes/{inbox_id}/files`
- Auth: HTTP bearer

Lists the inbox's files in path order, pending ones included, optionally only those whose path starts with
`path_prefix`. A prefix matches characters, not whole segments: `reports/q` matches `reports/q3.pdf`. Items
carry no download URL; get a file for one.

The list is read in the region that serves the request, so a file created or deleted a moment ago may not
show yet. Expired files never show.

Requires the `file_read` permission.

## Path parameters

- `inbox_id` string, required: The ID of the inbox.

## Query parameters

- `path_prefix` string
- `limit` integer: Limit of number of items returned.
- `page_token` string: Page token for pagination.
- `ascending` boolean

## Response `200`

Response with status 200

- FilesListFilesResponse
  - `count` integer, required: Number of items returned.
  - `limit` integer, required: Limit of number of items returned.
  - `next_page_token` string: Page token for pagination.
  - `files` FilesFileItem[], required: The inbox's files in path order. A list has no download URLs; get a file for one.
    - `file_id` string, required: ID of the file. A UUID.
    - `inbox_id` string, required: The ID of the inbox.
    - `email` string, required: Email address of the inbox.
    - `path` string, required: Where the file lives in its inbox's drive, such as `reports/q3.pdf`. Unique within the inbox. Segments are separated by `/`, with no leading or trailing `/`, no empty, `.` or `..` segment, no `\` and no control or invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two spellings of one name are one path. Case is kept.
    - `name` string, required: The path's last segment. A download saves under this name.
    - `size` integer, required: Size of the file in bytes. At most 104,857,600 (100 MiB).
    - `content_type` string, required: The file's MIME type, such as `application/pdf`. Defaults to `application/octet-stream`.
    - `sha256` string, required: The base64 encoding of the file's 32-byte SHA-256 digest, as S3's `x-amz-checksum-sha256` takes it (44 characters, ending in `=`). S3 refuses an upload whose bytes don't match.
    - `status` 'pending' | 'ready', required: `pending` until its bytes are uploaded and the upload is completed, then `ready`. Only a `ready` file has a download URL. A pending file is deleted if it isn't completed within a day.
    - `created_at` string, date-time, required: When the file was created.
    - `updated_at` string, date-time, required: When the file last changed, such as when its upload was completed.
    - `expires_at` string, date-time: When the file expires. After it, the file is gone from get and list and its path is free; its bytes are deleted soon after. Absent for a file that never expires.

## Other responses

- `400`: Error response with status 400
- `403`: `code` says why: `forbidden` when the organization hasn't joined AgentMail Labs; `missing_permission` when the credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn't completed agent verification, and every file permission for an organization- or pod-scoped key under a content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn't fit the organization's Drive quota.
- `404`: Error response with status 404

## Changes

- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/:inbox_id/files/get.md)

---

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