Repository Public
1---2title: List Files3url: https://platform.claude.com/docs/en/api/beta/files/list4---56# List Files78**GET** `/v1/files`910List Files1112## Query parameters1314- `ids: optional array of string`1516 Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.1718- `limit: optional number`1920 Number of items to return per page.2122 Defaults to `20`. Ranges from `1` to `1000`.2324 default: 20, maximum: 1000, minimum: 12526- `page: optional string`2728 Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.2930- `scope_id: optional string`3132 Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).3334## Headers3536- `"anthropic-beta": optional array of AnthropicBeta`3738 Optional header to specify the beta version(s) you want to use.3940 - `string`4142 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`4344 - `"message-batches-2024-09-24"`4546 - `"prompt-caching-2024-07-31"`4748 - `"computer-use-2024-10-22"`4950 - `"computer-use-2025-01-24"`5152 - `"pdfs-2024-09-25"`5354 - `"token-counting-2024-11-01"`5556 - `"token-efficient-tools-2025-02-19"`5758 - `"output-128k-2025-02-19"`5960 - `"files-api-2025-04-14"`6162 - `"mcp-client-2025-04-04"`6364 - `"mcp-client-2025-11-20"`6566 - `"dev-full-thinking-2025-05-14"`6768 - `"interleaved-thinking-2025-05-14"`6970 - `"code-execution-2025-05-22"`7172 - `"extended-cache-ttl-2025-04-11"`7374 - `"context-1m-2025-08-07"`7576 - `"context-management-2025-06-27"`7778 - `"model-context-window-exceeded-2025-08-26"`7980 - `"skills-2025-10-02"`8182 - `"fast-mode-2026-02-01"`8384 - `"output-300k-2026-03-24"`8586 - `"user-profiles-2026-03-24"`8788 - `"user-profiles-2026-08-18"`8990 - `"user-profiles-2026-09-04"`9192 - `"advisor-tool-2026-03-01"`9394 - `"managed-agents-2026-04-01"`9596 - `"cache-diagnosis-2026-04-07"`9798 - `"dreaming-2026-04-21"`99100 - `"thinking-token-count-2026-05-13"`101102 - `"server-side-fallback-2026-06-01"`103104 - `"server-side-fallback-2026-07-01"`105106 - `"fallback-credit-2026-06-01"`107108 - `"fallback-credit-2026-07-01"`109110 - `"agent-memory-2026-07-22"`111112 - `"mid-conversation-tool-changes-2026-07-01"`113114 - `"compact-2026-01-12"`115116 - `"computer-use-2025-11-24"`117118 - `"mcp-tunnels-2026-06-22"`119120 - `"structured-outputs-2025-11-13"`121122 - `"task-budgets-2026-03-13"`123124 - `"thinking-display-updates-2026-08-18"`125126 - `"ce-user-management-2026-07-13"`127128 - `"mid-conversation-output-config-2026-07-01"`129130 - `"thinking-binding-controls-2026-08-01"`131132 - `"mid-conversation-system-clear-at-2026-08-21"`133134 - `"compact-2026-09-04"`135136- `"anthropic-workspace-id": optional string`137138## Returns139140- `data: array of BetaFileMetadata`141142 List of file metadata objects.143144 - `type: "file"`145146 Object type.147148 For files, this is always `"file"`.149150 - `id: string`151152 Unique object identifier.153154 The format and length of IDs may change over time.155156 - `created_at: string`157158 RFC 3339 datetime string representing when the file was created.159160 format: date-time161162 - `filename: string`163164 Original filename of the uploaded file.165166 maxLength: 500, minLength: 1167168 - `mime_type: string`169170 MIME type of the file.171172 maxLength: 255, minLength: 1173174 - `size_bytes: number`175176 Size of the file in bytes.177178 minimum: 0179180 - `downloadable: optional boolean`181182 Whether the file can be downloaded.183184 default: false185186 - `expires_at: optional string or null`187188 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.189190 format: date-time191192 - `scope: optional BetaFileScope or null`193194 The scope of this file, indicating the context in which it was created (e.g., a session).195196 - `type: "session"`197198 The type of scope (e.g., `"session"`).199200 - `id: string`201202 The ID of the scoping resource (e.g., the session ID).203204- `next_page: optional string or null`205206 Opaque cursor for the next page. Supply as `?page=` to fetch the next page; null when there are no more results.207208## Example209210```bash211curl https://api.anthropic.com/v1/files \212 -H 'anthropic-version: 2023-06-01' \213 -H "X-Api-Key: $ANTHROPIC_API_KEY"214```215216### Response (200)217218```json219{220 "data": [221 {222 "id": "file_011CNha8iCJcU1wXNR6q4V8w",223 "created_at": "2025-04-15T18:37:24.100435Z",224 "filename": "document.pdf",225 "mime_type": "application/pdf",226 "size_bytes": 102400,227 "type": "file",228 "downloadable": false,229 "expires_at": "2025-05-15T18:37:24.100435Z",230 "scope": {231 "id": "id",232 "type": "session"233 }234 }235 ],236 "next_page": "next_page"237}238```239