> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# List Files

> List the files in the authenticated organization, with filters and cursor pagination

Requires [version 2.0.0](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0) or later of the Archetype platform.

## Overview

This endpoint returns a cursor-paginated list of the files in your organization that you can
see. It takes the same query parameters and returns the same page shape as [List Files
Metadata](https://docs.archetypeai.app/api-reference/files/get-all-metadata.md), and adds a `filename` filter for an exact name match. Files that
are being deleted or are already deleted aren't listed. Filters are applied before pagination.

The list is ordered on the field named by `sort`, in the direction given by `order`. The default
is newest `created_at` first. Ties are broken on the `file_uid`, so the same request returns the
same page while no files change.

> [!NOTE]
>
> When paging, be sure to keep `sort` and `order` the same.

A page holds up to `limit` files (default 100, at most 1000). To read the next page, pass the
previous page's `next_cursor` as `after`; to step back, pass its `prev_cursor` as `before`.
`has_more` refers to the direction being travelled. Cursors are opaque tokens tied to the `sort`
they were minted under and must not be constructed by the client.

## Query Parameters

**limit** `integer` (default: 100)

Page size, between `1` and `1000`. Values outside that range are clamped.

**after** `string`

Opaque cursor from a previous page's `next_cursor` (or its `prev_cursor` after paging
backward): returns the rows past it in the requested order. Mutually exclusive with `before`;
a cursor minted under a different `sort` is rejected with an HTTP `400` error.

**before** `string`

Opaque cursor from a previous page's `prev_cursor` (or its `next_cursor` after paging
backward): returns the rows before it in the requested order. Mutually exclusive with `after`.

**file\_type** `string`

Filter results to a comma-delineated list of up to 50 MIME file types (e.g. `image/png`,
`text/csv,application/json`). Omit to return files of all types.

**search** `string`

Case-insensitive substring match against file names. An empty string is ignored.

**filename** `string`

Exact match against file names. The page holds at most the one file with this name. An empty
string is ignored.

**sort** `string`

Specifies the field on which the returned list is ordered. Must be one of the following:

| Value | Description |
| - | - |
| `created_at` | Sort by the time and date at which the file was created. **Default value.** |
| `file_id` | Sort by the file's name |
| `file_status` | Sort by the file's lifecycle status, in this order: uploading, registered, ingested, corrupt |
| `num_bytes` | Sort by the size of the file in bytes |

**order** `string`

Specifies whether sorting is performed in ascending order (`asc`) or descending order
(`desc`). When sorting by `created_at` or `num_bytes`, this defaults to `desc`. When sorting by
`file_status` or `file_id`, this defaults to `asc`.

## Response

Returns one page of file metadata records, along with the cursors to move off it. When the page
is past the end of the file list, `data` is empty and `has_more` is `false`.

**data** `array` *required*

The files on this page, in the requested `sort` and `order` whether the page was reached with
`after` or `before`. Each record has the same shape as the response from [Get
File](https://docs.archetypeai.app/api-reference/files/get-file.md).

**has\_more** `boolean` *required*

Whether more files exist in the direction this page was fetched.

**next\_cursor** `string`

Cursor continuing in the direction of travel: pass it as `after` on a forward page, or as
`before` when this request itself used `before`. `null` when `has_more` is `false`.

**prev\_cursor** `string`

Cursor stepping back the way this page was reached: pass it as `before` after a forward page,
or as `after` after a backward one. `null` when the request carried no cursor (the first page).

An HTTP `400` error is returned for an invalid `sort` or `order`, when both `after` and `before`
are given, for a malformed cursor or one minted under another `sort`, or when `file_type` lists
more than 50 MIME types.

```bash cURL - First Page theme={"system"}
curl https://platform.u1.archetypeai.app/api/files \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

```bash cURL - By Filename theme={"system"}
curl "https://platform.u1.archetypeai.app/api/files?filename=training-data.csv" \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

```python Python theme={"system"}
import requests
import os

api_key = os.environ.get("ATAI_API_KEY")

response = requests.get(
    "https://platform.u1.archetypeai.app/api/files",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"limit": 100},
)

page = response.json()
for file in page["data"]:
    print(f"{file['file_uid']}  {file['file_id']}  {file['file_status']}")

# Pass the cursor back verbatim as `after` to fetch the next page.
if page["has_more"]:
    print(f"Next page cursor: {page['next_cursor']}")
```

```javascript JavaScript theme={"system"}
const params = new URLSearchParams({
  limit: "100",
});

const response = await fetch(
  `https://platform.u1.archetypeai.app/api/files?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
    },
  }
);

const page = await response.json();
for (const f of page.data) {
  console.log(`${f.file_uid}  ${f.file_id}  ${f.file_status}`);
}

// Pass the cursor back verbatim as `after` to fetch the next page.
if (page.has_more) {
  console.log(`Next page cursor: ${page.next_cursor}`);
}
```

```json 200 - Success theme={"system"}
{
  "data": [
    {
      "file_id": "training-data.csv",
      "file_uid": "fil_01k7x3q9m2v8n4p6r5t0w1y2z3",
      "is_valid": true,
      "file_type": "text/csv",
      "num_bytes": 12483910,
      "created_at": "2026-10-21T09:12:44Z",
      "file_status": "FILE_STATUS_INGESTED",
      "file_attributes": {
        "num_rows": 50000,
        "num_columns": 24,
        "column_headers": ["timestamp", "value", "label"]
      },
      "ingested": true,
      "file_index": 0,
      "file_tags": {}
    }
  ],
  "has_more": true,
  "next_cursor": "<cursor>",
  "prev_cursor": null
}
```

```json 401 - Unauthorized theme={"system"}
{
  "errors": [
    {
      "code": "unauthorized_request",
      "message": "Unauthorized or invalid access.",
      "suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.