> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt.

# List Files

GET https://api.agentmail.to/v0/inboxes/{inbox_id}/files

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.

Reference: https://docs.agentmail.to/api-reference/inboxes/files/list

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.agentmail.to` (prod, default)
- `https://x402.api.agentmail.to` (prod-x402)
- `https://mpp.api.agentmail.to` (prod-mpp)
- `https://api.agentmail.eu` (eu-prod)

## Request

### Path parameters

- `inbox_id` (string, required) — The ID of the inbox.

### Query parameters

- `path_prefix` (string, optional) — Only files whose path starts with this. Held to the path rules, except it may stop partway.
- `limit` (integer, optional) — Page size, 100 by default and at most 500.
- `page_token` (string, optional) — Page token for pagination.
- `ascending` (boolean, optional) — Path order, `true` by default. `false` lists in reverse.

## Response

### 200

- `count` (integer, required) — Number of items returned.
- `limit` (integer, required) — Limit of number of items returned.
- `files` (list of FileItem, required) — The inbox's files in path order. A list has no download URLs; get a file for one.
- `next_page_token` (string, optional) — Page token for pagination.

## Errors

### 400 Validation Error

- `name` (string, required) — Name of error.
- `errors` (any, required) — Validation errors. Each entry has a path and a message identifying the invalid field.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `message` (string, optional) — Error message.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 403 File Forbidden Error

`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.

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 404 Not Found Error

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

## Types

### FileItem

A file, as a list returns it.

- `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` (enum, 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.
  - Allowed values: `pending`, `ready`
- `created_at` (datetime, required) — When the file was created.
- `updated_at` (datetime, required) — When the file last changed, such as when its upload was completed.
- `expires_at` (datetime, optional) — 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.

## Examples

**Response**

```json
{
  "count": 1,
  "limit": 100,
  "files": [
    {
      "file_id": "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f",
      "inbox_id": "reports@agentmail.to",
      "email": "reports@agentmail.to",
      "path": "reports/q3.pdf",
      "name": "q3.pdf",
      "size": 48213,
      "content_type": "application/pdf",
      "sha256": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
      "status": "ready",
      "created_at": "2026-10-14T16:20:00Z",
      "updated_at": "2026-10-14T16:20:05Z"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files"

querystring = {"path_prefix":"reports/"}

headers = {"Authorization": "Bearer <api_key>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F';
const options = {method: 'GET', headers: {Authorization: 'Bearer <api_key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F")
  .header("Authorization", "Bearer <api_key>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files?path_prefix=reports%2F")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```