Skip to main content

List environment files

Query files already on disk in an environment with directory pagination.

Endpoint

GET /agents/environments/{environment_id}/files Queries live files in the specified environment. A successful call returns 200 and directory pagination. This endpoint verifies that files are on disk and does not return file content.

Query parameters

path string (optional)Directory path, optional, restricts results to an existing absolute directory under /workspace/limit integer (optional)Number of items per pagepage string (optional)Pagination cursor; omit on the first request, then pass the next returned by the previous pageThe request parameter is page and the response cursor field is next; this is not the after cursor used by source files or artifacts.

Request example

curl -sS --get "$BASE_URL/agents/environments/ccarenv_xxx/files" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --data-urlencode "path=/workspace/input/" \
  --data-urlencode "limit=20"

Response fields

object stringPage object type, fixed as pagedata arrayEnvironment files on this pagenext string / nullCursor for the next page; null when there is no next pagehas_more booleanWhether another page existsEach item in data[] contains:The response contains a data array for the current page and a cursor for the next page. When the directory is empty, data is an empty array.
environment_id stringEnvironment IDobject stringEnvironment file object type, fixed as agent.environment.filepath stringFile path in the environmentsize_bytes integerFile size in bytes

Response example

{
  "object": "page",
  "data": [
    {
      "environment_id": "ccarenv_xxx",
      "object": "agent.environment.file",
      "path": "/workspace/input/input.txt",
      "size_bytes": 18
    }
  ],
  "next": null,
  "has_more": false
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorPass an existing absolute directory under /workspace/
404not_found_error / not_found_errorUse an environment ID that exists and is visible in the current workspace
The error body has the shape {"error":{"type","code","message","param"}}. Gateway errors can use a different structure.