> ## 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 > Returns a paginated list of box instances. Use this endpoint to monitor environments, filter by status or type, or retrieve boxes by labels or device type. ## OpenAPI ````yaml get /boxes 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: get: tags: - Box summary: List box description: >- Returns a paginated list of box instances. Use this endpoint to monitor environments, filter by status or type, or retrieve boxes by labels or device type. operationId: BoxController_listBox parameters: - name: page required: false in: query description: Page number schema: default: 1 example: 1 type: integer - name: pageSize required: false in: query description: Page size schema: default: 10 example: 10 type: integer - name: status required: false in: query description: >- Filter boxes by their current status (pending, running, stopped, error, terminated, all). Must be an array of statuses. Use 'all' to get boxes with any status. schema: title: BoxStatusFilter default: - running - pending example: - running type: array items: enum: - all - pending - running - error - terminated - name: type required: false in: query description: >- Filter boxes by their type (linux, android, all). Must be an array of types. Use 'all' to get boxes of any type. schema: title: BoxTypeFilter default: - all example: - linux type: array items: enum: - all - linux - android - name: labels required: false in: query description: >- Filter boxes by their labels. Labels are key-value pairs that help identify and categorize boxes. Use this to filter boxes that match specific label criteria. For example, you can filter by project, environment, team, or any custom labels you've added to your boxes. schema: $ref: '#/components/schemas/Object' - name: deviceType required: false in: query description: Filter boxes by their device type (virtual, physical) schema: title: BoxDeviceTypeFilter example: virtual type: string responses: '200': description: List box content: application/json: schema: $ref: '#/components/schemas/ListBoxResult' security: - bearer: [] x-codeSamples: - lang: JavaScript source: |- import GboxSDK 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 boxes = await gboxSDK.list(); boxes.operators.forEach((operator) => { console.log(operator.data.id); }); const boxInfo = await gboxSDK.listInfo(); boxInfo.data.forEach((item) => { console.log(item.id); }); } main(); - lang: Python source: |- import os from gbox_sdk import GboxSDK gbox_sdk = GboxSDK(api_key=os.environ["GBOX_API_KEY"]) boxes = gbox_sdk.list() for operator in boxes.operators: print(operator.data.id) box_info = gbox_sdk.list_info() for item in box_info.data: print(item.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\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\tboxes, err := gboxSDK.List(context.Background())\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to list boxes: %v\", err)\n\t}\n\n\tfor _, operator := range boxes.Operators {\n\t\tfmt.Println(operator.Data.ID)\n\t}\n\n\tboxInfo, err := gboxSDK.ListInfo(context.Background())\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to list box info: %v\", err)\n\t}\n\n\tfor _, item := range boxInfo.Data {\n\t\tfmt.Println(item.ID)\n\t}\n}" components: schemas: Object: type: object properties: {} ListBoxResult: type: object properties: total: type: integer description: Total number of items example: 100 page: type: integer description: Page number default: 1 example: 1 pageSize: type: integer description: Page size default: 10 example: 10 data: description: A box instance that can be either Linux or Android type title: QueryBoxResult example: - id: c9bdc193-b54b-4ddb-a035-5ac0c598d32d type: linux status: running createdAt: '2024-01-15T10:30:00.000Z' updatedAt: '2024-01-15T10:35:00.000Z' expiresAt: '2024-01-15T10:40:00.000Z' config: os: version: ubuntu-20.04 workingDir: /home/user labels: environment: development envs: NODE_ENV: production cpu: 2 memory: 1024 storage: 30 - id: f7e8a2c1-9d4e-4b3a-8c6f-1e5d7a9b2c4e type: android status: pending createdAt: '2024-01-15T10:32:00.000Z' updatedAt: '2024-01-15T10:32:00.000Z' expiresAt: '2024-01-15T10:47:00.000Z' config: os: version: '12' deviceType: virtual workingDir: /data/local/tmp labels: app: mobile-testing envs: ANDROID_HOME: /opt/android-sdk cpu: 2 memory: 2048 storage: 20 type: array items: oneOf: - $ref: '#/components/schemas/LinuxBox' - $ref: '#/components/schemas/AndroidBox' title: List Box Result description: Response containing paginated list of box instances required: - total - page - pageSize - data LinuxBox: type: object properties: id: type: string description: Unique identifier for the box title: BaseBox example: c9bdc193-b54b-4ddb-a035-5ac0c598d32d status: type: string enum: - pending - running - error - terminated description: The current status of a box instance title: BaseBox example: running createdAt: format: date-time type: string description: Creation timestamp of the box title: BaseBox example: '2024-01-15T10:30:00.000Z' updatedAt: format: date-time type: string description: Last update timestamp of the box title: BaseBox example: '2024-01-15T10:35:00.000Z' expiresAt: type: string format: date-time description: Expiration timestamp of the box title: BaseBox example: '2024-01-15T10:40:00.000Z' nullable: true reason: type: string description: The reason for the current status, if any title: BaseBox example: Box terminated by user nullable: true type: type: string enum: - linux default: linux description: Box type is Linux title: LinuxBox example: linux config: description: Configuration for a Linux box instance title: LinuxBox example: os: version: ubuntu-20.04 deviceType: physical workingDir: /home/user labels: environment: development team: qa envs: NODE_ENV: production PATH: /usr/bin:/bin cpu: 2 memory: 1024 storage: 30 allOf: - $ref: '#/components/schemas/LinuxConfig' title: Linux Box description: Linux box instance with full configuration and status required: - id - status - createdAt - updatedAt - expiresAt - type - config AndroidBox: type: object properties: id: type: string description: Unique identifier for the box title: BaseBox example: c9bdc193-b54b-4ddb-a035-5ac0c598d32d status: type: string enum: - pending - running - error - terminated description: The current status of a box instance title: BaseBox example: running createdAt: format: date-time type: string description: Creation timestamp of the box title: BaseBox example: '2024-01-15T10:30:00.000Z' updatedAt: format: date-time type: string description: Last update timestamp of the box title: BaseBox example: '2024-01-15T10:35:00.000Z' expiresAt: type: string format: date-time description: Expiration timestamp of the box title: BaseBox example: '2024-01-15T10:40:00.000Z' nullable: true reason: type: string description: The reason for the current status, if any title: BaseBox example: Box terminated by user nullable: true type: type: string enum: - android default: android description: Box type is Android title: AndroidBox example: android config: description: Configuration for an Android box instance title: AndroidBox example: os: version: '12' deviceType: virtual workingDir: /data/local/tmp labels: app: mobile-testing env: staging envs: ANDROID_HOME: /opt/android-sdk DISPLAY: ':1' cpu: 2 memory: 2048 storage: 20 allOf: - $ref: '#/components/schemas/AndroidConfig' title: Android Box description: Android box instance with full configuration and status required: - id - status - createdAt - updatedAt - expiresAt - type - config LinuxConfig: type: object properties: os: description: Operating system configuration title: LinuxConfig example: version: ubuntu-20.04 allOf: - $ref: '#/components/schemas/LinuxOsConfig' workingDir: type: string description: >- Working directory path for the box. This directory serves as the default starting point for all operations including command execution, code running, and file system operations. When you execute commands or run code, they will start from this directory unless explicitly specified otherwise. title: LinuxConfig example: /home/user labels: type: object additionalProperties: type: string description: >- Key-value pairs of labels for the box. Labels are used to add custom metadata to help identify, categorize, and manage boxes. Common use cases include project names, environments, teams, applications, or any other organizational tags that help you organize and filter your boxes. title: LinuxConfig example: project: web-scraper environment: production team: backend version: v1.2.0 envs: type: object additionalProperties: type: string description: >- Environment variables for the box. These variables will be available in all operations including command execution, code running, and other box behaviors title: LinuxConfig example: MY_ENV_KEY: env value cpu: type: number description: CPU cores allocated to the box title: LinuxConfig example: 2 memory: type: number description: Memory allocated to the box in MiB title: LinuxConfig example: 1024 storage: type: number description: Storage allocated to the box in GiB. title: LinuxConfig example: 30 publicIp: type: string description: Public IP allocated to the box. title: LinuxConfig example: 8.8.8.8 deviceType: type: string enum: - container - vm description: Device type - container or vm Linux device title: LinuxConfig example: container default: container snapshotName: type: string description: Snapshot name title: LinuxConfig snapshotId: type: string description: Snapshot id title: LinuxConfig title: Linux Config description: Complete configuration for Linux box instance required: - os - workingDir - labels - envs - cpu - memory - storage - publicIp AndroidConfig: type: object properties: os: description: Android operating system configuration title: AndroidConfig example: version: '12' allOf: - $ref: '#/components/schemas/AndroidOsConfig' deviceType: type: string enum: - virtual - physical description: Device type - virtual or physical Android device title: AndroidConfig example: virtual default: virtual workingDir: type: string description: >- Working directory path for the box. This directory serves as the default starting point for all operations including command execution, code running, and file system operations. When you execute commands or run code, they will start from this directory unless explicitly specified otherwise. title: AndroidConfig example: /data/local/tmp labels: type: object additionalProperties: type: string description: >- Key-value pairs of labels for the box. Labels are used to add custom metadata to help identify, categorize, and manage boxes. Common use cases include project names, environments, teams, applications, or any other organizational tags that help you organize and filter your boxes. title: AndroidConfig example: app: mobile-testing environment: staging team: qa device: pixel-6 envs: type: object additionalProperties: type: string description: >- Environment variables for the box. These variables will be available in all operations including command execution, code running, and other box behaviors title: AndroidConfig example: ANDROID_HOME: /opt/android-sdk DISPLAY: ':1' cpu: type: number description: CPU cores allocated to the box title: AndroidConfig example: 2 memory: type: number description: Memory allocated to the box in MiB title: AndroidConfig example: 2048 storage: type: number description: Storage allocated to the box in GiB title: AndroidConfig example: 20 title: Android Config description: Complete configuration for Android box instance required: - os - labels - envs - cpu - memory - storage LinuxOsConfig: type: object properties: version: type: string description: OS version string (e.g. 'ubuntu-20.04') title: LinuxOsConfig example: ubuntu-20.04 title: Linux OS Config description: Linux operating system configuration required: - version AndroidOsConfig: type: object properties: version: type: string enum: - '12' - '13' - '15' description: Supported Android versions title: AndroidOsConfig example: '12' title: Android OS Config description: Android operating system configuration required: - version securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http description: >- Enter your API Key in the format: Bearer . Get it from https://gbox.ai ````