# List Files

Returns a list of files that belong to the user, with cursor-based pagination.

## Endpoint

```http
GET /files
```

operationId: `listFiles`

### Servers

- `https://api.deepseek.com`

## Authentication

### Alternative 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

```yaml
type: http
scheme: bearer
```

## Parameters

**`after`** (query) — optional

A `file_id` cursor for pagination. Returns files listed after this one.

- `type`: `string`

**`limit`** (query) — optional

The number of files to return. Must be between 1 and 1000.

- `type`: `integer`

- `minimum`: `1`

- `maximum`: `1000`

- `default`: `1000`

**`order`** (query) — optional

Sort order by creation time. `asc` for ascending, `desc` for descending.

- `type`: `string`

- `enum`: `["asc","desc"]`

- `default`: `asc`

**`purpose`** (query) — optional

Only return files with the given purpose.

- `type`: `string`

- `enum`: `["user_data","text_recognition","rich_layout_recognition"]`

## Responses

### 200

OK, returns a list of `file object`.

#### application/json

- Reference: [ListFilesResponse](#schema-list-files-response) (`#/components/schemas/ListFilesResponse`)

**Example**

```json
{
  "object": "list",
  "data": [
    {
      "id": "file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9",
      "object": "file",
      "bytes": 102400,
      "created_at": 1700000000,
      "filename": "image.jpg",
      "purpose": "user_data"
    }
  ],
  "first_id": "file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "last_id": "file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "has_more": false
}
```

## Code samples

### curl

```bash
# Set DEEPSEEK_API_KEY to your API key before running this example.
curl --silent --show-error --max-time 60 "https://api.deepseek.com/files?limit=2" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}"
```

### Python — OpenAI SDK

```python
# Set DEEPSEEK_API_KEY to your API key before running this example.
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    timeout=60.0,
)

files = client.files.list(limit=2)
print(files.model_dump_json(indent=2))
```

## Referenced schemas

### schema-list-files-response

**ListFilesResponse** — `#/components/schemas/ListFilesResponse`

- `type`: `object`

- `required`: `["object","data","has_more"]`

- **Properties**

  - **`object`** (required)

    The object type, which is always `list`.

    - `type`: `string`

    - `enum`: `["list"]`

  - **`data`** (required)

    The list of file objects.

    - `type`: `array`

    - **Array items**

      - Reference: [FileObject](#schema-file-object) (`#/components/schemas/FileObject`)

  - **`first_id`** (optional)

    The ID of the first file in the list. Useful as a pagination cursor.

    - `type`: `string`

  - **`last_id`** (optional)

    The ID of the last file in the list. Useful as a pagination cursor.

    - `type`: `string`

  - **`has_more`** (required)

    Whether there are more files beyond this page.

    - `type`: `boolean`

### schema-file-object

**FileObject** — `#/components/schemas/FileObject`

Describes a file that has been uploaded to the Files API. A file uploaded with an OCR purpose is returned only after parsing succeeds.

- `type`: `object`

- `required`: `["id","object","bytes","created_at","filename","purpose"]`

- **Properties**

  - **`id`** (required)

    The file identifier, of the form `file-api-...`, which can be referenced in chat completion requests.

    - `type`: `string`

  - **`object`** (required)

    The object type, which is always `file`.

    - `type`: `string`

    - `enum`: `["file"]`

  - **`bytes`** (required)

    The size of the file in bytes.

    - `type`: `integer`

  - **`created_at`** (required)

    The Unix timestamp (in seconds) of when the file was created.

    - `type`: `integer`

  - **`filename`** (required)

    The name of the file.

    - `type`: `string`

  - **`purpose`** (required)

    The intended purpose of the file.

    - `type`: `string`

    - `enum`: `["user_data","text_recognition","rich_layout_recognition"]`

  - **`expires_at`** (optional)

    The Unix timestamp (in seconds) of when the file expires. Only present when an expiration was set at upload time.

    - `type`: `integer`
