> ## Documentation Index > Fetch the complete documentation index at: https://docs.gbox.ai/llms.txt > Use this file to discover all available pages before exploring further. # List box files > Lists files and directories in a box. You can specify the directory path and depth, and optionally a working directory. The response includes metadata such as type, size, permissions, and last modified time. ## OpenAPI ````yaml get /boxes/{boxId}/fs/list openapi: 3.0.0 info: title: GBOX Open API description: GBOX Open API Documentation version: '1.0' contact: {} servers: - url: https://gbox.ai/api/v1 description: Production Server security: [] tags: [] paths: /boxes/{boxId}/fs/list: get: tags: - File System summary: List box files description: >- Lists files and directories in a box. You can specify the directory path and depth, and optionally a working directory. The response includes metadata such as type, size, permissions, and last modified time. operationId: FileSystemController_listFiles parameters: - name: boxId required: true in: path description: Box ID schema: example: c9bdc193-b54b-4ddb-a035-5ac0c598d32d type: string - name: workingDir required: false in: query description: >- Working directory. If not provided, the file will be read from the `box.config.workingDir` directory. schema: title: FileSystemBase example: /home/user/documents type: string - name: path required: true in: query description: Target directory path in the box schema: title: ListFile example: /home/user/documents type: string - name: depth required: false in: query description: Depth of the directory schema: title: ListFile default: 1 example: 2 type: number responses: '200': description: List files content: application/json: schema: $ref: '#/components/schemas/ListFileResult' '404': description: Directory not found security: - bearer: [] x-codeSamples: - lang: JavaScript source: |- import GboxSDK, { isFileOperator } from "gbox-sdk"; const gboxSDK = new GboxSDK({ apiKey: process.env["GBOX_API_KEY"] // This is the default and can be omitted }); async function main() { const box = await gboxSDK.create({ type: "linux" }); const listResult = await box.fs.list({ path: "/tmp", depth: 2, }); const files = listResult.filter(isFileOperator); for (const file of files) { // you can read the file content const { content } = await file.read(); console.info(`📄 ${file.data.name} (${file.data.size}) - ${file.data.path}`); console.info(`file content: ${content}`); } // List files in the home directory const listInfo = await box.fs.listInfo({ path: "/tmp", depth: 2, }); console.log("Files and directories:"); console.info(JSON.stringify(listInfo, null, 2)); } main(); - lang: Python source: |- import os import json from gbox_sdk import GboxSDK from gbox_sdk.utils import is_file_operator def main(): gbox_sdk = GboxSDK(api_key=os.environ["GBOX_API_KEY"]) box = gbox_sdk.create(type="linux") list_result = box.fs.list( path="/tmp", depth=2 ) files = [item for item in list_result if is_file_operator(item)] for file in files: # you can read the file content content = file.read() print(f"📄 {file.data.name} ({file.data.size}) - {file.data.path}") print(f"file content: {content}") # List files in the home directory list_info = box.fs.list_info( path="/tmp", depth=2 ) print("Files and directories:") print(list_info) if __name__ == "__main__": main() - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\t\"github.com/gbox/gbox-sdk-go\"\n)\n\nfunc main() {\n\tgboxSDK := gbox.NewGboxSDK(os.Getenv(\"GBOX_API_KEY\"))\n\n\tbox, err := gboxSDK.Create(context.Background(), gbox.CreateOptions{Type: \"linux\"})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to create linux box: %v\", err)\n\t}\n\n\tlistResult, err := box.Fs.List(context.Background(), &gbox.ListFileRequest{\n\t\tPath: \"/tmp\",\n\t\tDepth: 2,\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to list files: %v\", err)\n\t}\n\n\tfiles := gbox.FilterFiles(listResult)\n\n\tfor _, file := range files {\n\t\t// you can read the file content\n\t\tcontent, err := file.Read(context.Background())\n\t\tif err != nil {\n\t\t\tlog.Printf(\"Failed to read file %s: %v\", file.Data().Name, err)\n\t\t\tcontinue\n\t\t}\n\t\tfmt.Printf(\"📄 %s (%s) - %s\\n\", file.Data().Name, file.Data().Size, file.Data().Path)\n\t\tfmt.Printf(\"file content: %s\\n\", content)\n\t}\n\n\t// List files in the home directory\n\tlistInfo, err := box.Fs.ListInfo(context.Background(), &gbox.ListFileRequest{\n\t\tPath: \"/tmp\",\n\t\tDepth: 2,\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to list files info: %v\", err)\n\t}\n\n\tfmt.Println(\"Files and directories:\")\n\tlistInfoJSON, _ := json.MarshalIndent(listInfo, \"\", \" \")\n\tfmt.Printf(\"%s\\n\", string(listInfoJSON))\n}" components: schemas: ListFileResult: type: object properties: data: description: Array of files and directories title: QueryBoxResult example: - type: dir name: projects path: /home/user/documents/projects/ mode: '755' lastModified: '2024-01-15T10:30:00.000Z' - type: file name: readme.txt path: /home/user/documents/readme.txt size: 1.2KB mode: '644' lastModified: '2024-01-15T10:30:00.000Z' type: array items: oneOf: - $ref: '#/components/schemas/File' - $ref: '#/components/schemas/Dir' title: List File Result description: Response containing directory listing results required: - data File: type: object properties: type: type: string enum: - file description: File type indicator title: File name: type: string description: Name of the file title: File example: example.txt path: type: string description: Full path to the file in the box title: File example: /path/to/example.txt size: type: string description: Size of the file title: File example: 10MB mode: type: string description: File metadata title: File example: '755' lastModified: format: date-time type: string description: Last modified time of the file title: File example: '2021-01-01T00:00:00Z' title: File description: File system file representation required: - type - name - path - size - mode - lastModified Dir: type: object properties: type: type: string enum: - dir description: Directory type indicator title: Dir name: type: string description: Name of the directory title: Dir example: example path: type: string description: Full path to the directory in the box title: Dir example: /path/to/example/ mode: type: string description: Directory metadata title: Dir example: '755' lastModified: format: date-time type: string description: Last modified time of the directory title: Dir example: '2021-01-01T00:00:00Z' title: Directory description: File system directory representation required: - type - name - path - mode - lastModified securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http description: >- Enter your API Key in the format: Bearer . Get it from https://gbox.ai ````