---
title: "List files"
method: GET
path: "/files"
tags: ["Files"]
---

# List files

`GET /files`

Lists files belonging to the workspace of the authenticating API key.

## Query parameters

- `limit` integer — Maximum number of files to return (1–1000).
- `cursor` string — Opaque pagination cursor from a previous response.
- `workspace_id` string, uuid — Workspace to scope the request to. Defaults to the caller’s default workspace.
- `provider` 'openai' | 'anthropic' — Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.
- `after` string — OpenAI-style forward cursor: the id to list after.
- `after_id` string — Anthropic-style forward cursor: the id to list after.
- `before_id` string — Anthropic-style reverse cursor. Not supported by OpenRouter storage.
- `order` 'asc' | 'desc' — Sort direction. Only `asc` is supported by OpenRouter storage.

## Response `200`

A page of files.

- union — A page of files, in the negotiated shape.
  - OpenRouterFileList — A page of files in the OpenRouter shape.
    - `_shape` 'openrouter', required
    - `cursor` string, nullable, required — Opaque cursor for the next page; null when there are no more results.
    - `data` OpenRouterFile[], required
      - `_shape` 'openrouter', required
      - `created_at` string, required
      - `downloadable` boolean, required
      - `filename` string, required
      - `id` string, required
      - `mime_type` string, required
      - `size_bytes` integer, required
      - `type` 'file', required
    - `first_id` string, nullable, required
    - `has_more` boolean, required
    - `last_id` string, nullable, required
  - OpenAIFileList — A page of files in OpenAI's shape.
    - `_shape` 'openai', required
    - `data` OpenAIFile[], required
      - `_shape` 'openai', required
      - `bytes` integer, required
      - `created_at` integer, required
      - `filename` string, required
      - `id` string, required
      - `object` 'file', required
      - `purpose` 'assistants' | 'batch' | 'fine-tune' | 'vision' | 'user_data' | 'evals' | 'assistants_output' | 'batch_output' | 'fine-tune-results', required
      - `status` 'processed', required
    - `first_id` string, nullable, required
    - `has_more` boolean, required
    - `last_id` string, nullable, required
    - `object` 'list', required
  - AnthropicFileList — A page of files in Anthropic's shape.
    - `_shape` 'anthropic', required
    - `data` AnthropicFile[], required
      - `_shape` 'anthropic', required
      - `created_at` string, required
      - `downloadable` boolean, required
      - `filename` string, required
      - `id` string, required
      - `mime_type` string, required
      - `size_bytes` integer, required
      - `type` 'file', required
    - `first_id` string, nullable, required
    - `has_more` boolean, required
    - `last_id` string, nullable, required

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Authentication successful but insufficient permissions
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error
- `502` — Bad Gateway - Provider/upstream API failure
- `503` — Service Unavailable - Service temporarily unavailable

---

[API](https://skmtc.net/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.net/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/versions/f3788187f5b7/schema)