List Workspace Files

GET/v1/agents/sessions/{session_id}/workspace-files

List current file paths and sizes in one Session workspace directory. This is a metadata-only listing, not attachment history or artifact content. Unknown or repeated query parameters return 400.

Path parameters

stringsession_idrequired

Session ID (ses_ prefix).

Query parameters

Optional<string>path

Absolute directory /workspace or a normalized directory below it. Maximum 4096 bytes; no traversal, backslashes, or trailing slash.

Default: /workspace

Optional<integer>limit

Page size from 1 to 100.

Default: 20

Optional<string>order

Path sort order: asc or desc.

Default: asc

Optional<string>page

Opaque next value from the previous response. Omit on the first page; do not send an empty string. Keep path, order, and limit unchanged.

Response fields

stringobjectrequired

Always page.

arraydatarequired

Current directory files, each with path and size_bytes. This is not a recursive listing.

string | nullnextrequired

Pass this value as page to continue; null at the end.

booleanhas_morerequired

Whether another page is available.

curl --fail-with-body 'https://api.sandbase.ai/v1/agents/sessions/ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83/workspace-files' \
  -H "Authorization: Bearer $SANDBASE_API_KEY"

Response200 OK

{
  "object": "page",
  "data": [
    {
      "path": "/workspace/notes.md",
      "size_bytes": 1024
    }
  ],
  "next": null,
  "has_more": false
}

Workspace reads can return workspace_provisioning, workspace_environment_missing, workspace_cursor_invalid, or workspace_unavailable. If the cursor is invalid, restart from the first page. Use Artifacts to find downloadable generated outputs.