List files

GET /v1/files

Lists the files this key or its owner uploaded, or the files a session produced, newest first.

Without scope_id, the list holds files uploaded with a Task API key: the files this key uploaded, and the files that this key’s owner owns. With scope_id set to a session ID, the list holds the files that session’s agent produced, each with a scope field that names the session. That list leaves out the session’s attached files, the files the platform stores for the session (such as its transcript), and large tool results saved during the session. The list stays the same after the session is archived.

Send at most one of page, after_id and before_id. Both SDKs paginate with page.

The key must have the files:read capability. For what each capability allows, see Keys.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`20`	The maximum number of files to return. Must be between 1 and 100.
`page`	`string`	No		The `next_page` value from the previous response. Leave it out to get the first page.
`after_id`	`string`	No		The ID of a file. Returns files older than that file. Pass `last_id` from the previous page.
`before_id`	`string`	No		The ID of a file. Returns files newer than that file. Pass `first_id` from the previous page.
`scope_id`	`string`	No		A session ID. Returns the files that session’s agent produced instead of the default list.

Response

Returns 200 with a list of file objects, newest first.

Field	Description
`data`	The files on this page.
`first_id`	The ID of the first file on the page.
`last_id`	The ID of the last file on the page.
`has_more`	`true` when more files remain in the direction you are paging: older files for `page` and `after_id`, newer files for `before_id`.
`next_page`	The value to pass as `page` for the next page. It is `null` on the last page and on a `before_id` page.

{
  "data": [
    {
      "id": "329409ba-f288-4b44-9c73-14a18150edee",
      "created_at": "2026-10-21T01:41:11.028Z",
      "filename": "cities.csv",
      "mime_type": "text/csv",
      "size_bytes": 46,
      "type": "file",
      "downloadable": true
    }
  ],
  "next_page": null,
  "has_more": false,
  "first_id": "329409ba-f288-4b44-9c73-14a18150edee",
  "last_id": "329409ba-f288-4b44-9c73-14a18150edee"
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	`limit` is outside 1 to 100. Send a value from 1 to 100.
400	`invalid_request_error`	The request sends more than one of `page`, `after_id` and `before_id`. Send only one of them.
400	`invalid_request_error`	The request sends `ids`, which this API doesn’t take. Remove it.
404	`not_found_error`	`after_id` or `before_id` names a file that isn’t on this list. Pass `first_id` or `last_id` from a previous page of this list.
404	`not_found_error`	`scope_id` names a session this key can’t read. Pass the ID of a session this key can read.

Example

curl -sS "$CONTEXT_BASE_URL/v1/files?limit=20" -H "x-api-key: $CONTEXT_API_KEY"

# The files a session produced
curl -sS "$CONTEXT_BASE_URL/v1/files?scope_id=dd13d728-93e3-440a-874c-4efeb58c97e0" -H "x-api-key: $CONTEXT_API_KEY"

for file in client.beta.files.list(limit=20):  # auto-paginates
    print(file.id, file.filename, file.size_bytes)

# The files a session produced
for file in client.beta.files.list(scope_id="dd13d728-93e3-440a-874c-4efeb58c97e0"):
    print(file.id, file.filename)

for await (const file of client.beta.files.list({ limit: 20 })) console.log(file.id, file.filename)

// The files a session produced
for await (const file of client.beta.files.list({ scope_id: "dd13d728-93e3-440a-874c-4efeb58c97e0" })) console.log(file.id, file.filename)