ToAPIsToAPIs
User files

List user files

Page through the current account's registered files

GET
/api/v1/user/file

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

List the current account's registered files by creation time descending, then ID descending. Coverage is limited to registered files, not every historical storage object. The response contains no download URLs, storage paths, or prompts. Task associations may be filled in later.

This endpoint returns only data.items and data.next_cursor, with no has_more, meta, or total. Pass a nonempty next_cursor unchanged as the next request's cursor; the last page returns "" and an empty list returns []. Cursors are account-bound; tampered or cross-account cursors return 400. Only limit and cursor are supported, without time or deletion-state filters.

Authentication

Authorizationstringheaderrequired

Use a system access token: Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted and X-User-Id is not needed. Access is limited to the authenticated account's files and policy, without subaccount aggregation.

Request parameters

limitintegerquerydefault: 50

Items per page. Default 50, range 1-100.

cursorstringquery

The nonempty next_cursor from the previous page. Omit on the first page and stop when it is an empty string.

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/user/file?limit=50' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/user/file?limit=50",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.toapis.com/api/v1/user/file?limit=50", {
  method: "GET",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictional data. See Access for the shared response format.

data.itemsobject[]

Files on this page, or [] when empty.

data.items[].idstring

File ID used to delete one file with scope=single.

data.items[].sourcestring

Registration source, such as task_result, upload, or private_asset.

data.items[].task_kindstring | null

Optional associated task kind, such as generation or export.

data.items[].task_idstring | null

Optional associated task ID; null until linked.

data.items[].mime_typestring | null

MIME type, or null if unknown.

data.items[].size_bytesinteger | null

File size in bytes, or null if unknown.

data.items[].created_atstring

File creation time, not registration time.

data.items[].delete_statestring

none: not queued; pending: waiting; deleting: in progress; blocked: obstructed; deleted: legacy records only. The list does not retain a complete deletion history.

data.next_cursorstring

Next-page cursor, or an empty string on the last page.

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "123",
        "source": "task_result",
        "task_kind": "generation",
        "task_id": "task_example_01",
        "mime_type": "image/png",
        "size_bytes": 204800,
        "created_at": "2026-11-01T08:00:00Z",
        "delete_state": "none"
      }
    ],
    "next_cursor": ""
  }
}

Errors

Invalid limit, cursor, or query parameters return 400. Temporarily unavailable file reads return 503.

See Access for shared authentication, rate limits, and error handling.