List user files
Page through the current account's registered files
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
AuthorizationstringheaderrequiredUse 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: 50Items per page. Default 50, range 1-100.
cursorstringqueryThe 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[].idstringFile ID used to delete one file with scope=single.
data.items[].sourcestringRegistration source, such as task_result, upload, or private_asset.
data.items[].task_kindstring | nullOptional associated task kind, such as generation or export.
data.items[].task_idstring | nullOptional associated task ID; null until linked.
data.items[].mime_typestring | nullMIME type, or null if unknown.
data.items[].size_bytesinteger | nullFile size in bytes, or null if unknown.
data.items[].created_atstringFile creation time, not registration time.
data.items[].delete_statestringnone: not queued; pending: waiting; deleting: in progress; blocked: obstructed; deleted: legacy records only. The list does not retain a complete deletion history.
data.next_cursorstringNext-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.