--- title: List files description: List living files in a collection, oldest first. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # List files `GET /namespaces/{namespace}/collections/{collection}/files` List living files in a collection, oldest first. **Permission:** Cluster key, or a scoped key with read (write includes read). [API key types and authentication](/engine/reference/authentication.md). Lists return items and next_cursor. Keep the same key and filters for the next page. List cursors expire after one hour. path performs an exact lookup and returns zero or one item. prefix selects all paths that start with the supplied text. Send at most one. The result omits files being deleted. File responses never include inline text. ## Example request ```http GET /namespaces/acme/collections/incident-logs/files HTTP/1.1 Host: engine.example.com Authorization: Bearer ``` ## Path parameters ### `namespace` **string · required** Namespace name or ns_ ID. It must be visible to this key. ### `collection` **string · required** Collection name or col_ ID within the namespace. It must be visible to this key. ## Query parameters ### `path` **string · optional · nullable** Return only the file at this exact logical path. The page has zero or one item. Do not combine with prefix. ### `prefix` **string · optional · nullable** Return files whose paths start with this value. Use /reports/ for a directory boundary. Do not combine with path. ### `status` **string · optional · nullable** Return only files with this processing status. - `pending`: Waiting for bytes or processing. - `indexing`: Building searchable content. - `ready`: Available for retrieval. - `failed`: Processing failed. Inspect error. - `deleting`: Removal and cleanup are in progress. ### `cursor` **string · optional · nullable** Opaque continuation token from next_cursor. Keep the same key, filters, and other request values. Omit it for the first page. ### `limit` **integer · optional** Maximum resources in this page. Default 50, minimum 1, maximum 100. Default: `50`. - Minimum: 1 - Maximum: 100 ## Responses ### 200 · Success A page of living files. Exact path lookup returns zero or one item. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ```json { "items": [ { "id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6", "path": "/reports/incident.txt", "status": "ready", "source": { "type": "inline", "content_type": "text/plain", "bytes": 77 }, "metadata": { "environment": "production" }, "created_at": "2026-10-06T10:00:00Z", "updated_at": "2026-10-06T10:00:00Z" } ], "next_cursor": null } ``` #### Response fields ##### `items` **array · required** Page of files visible to this key. An empty array means no resources matched. ###### `items[].created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ###### `items[].error` **object · optional · nullable** Processing failure details. Omitted when the file has no error. ###### `items[].error.code` **string · required** Machine-readable reason for the failure. Use this value for program logic and message for display or diagnostics. ###### `items[].error.message` **string · required** Human-readable explanation of the failure. Do not parse this text to decide how to retry. ###### `items[].governing_rule` **object · optional · nullable** Rule that governs retrieval of this file. Present only when the collection enforces access rules. ###### `items[].governing_rule.file` **string · optional · nullable** Exact file target of the governing rule. Omitted for a folder rule. ###### `items[].governing_rule.folder` **string · optional · nullable** Folder prefix of the governing rule. Omitted for a file rule. ###### `items[].governing_rule.id` **string · required** Immutable ID of the rule that governs this file. ###### `items[].id` **string · required** Immutable file ID with the fil_ prefix. Retain this ID from the add response. ###### `items[].metadata` **map · required** Application data attached to the file, as a JSON object. Use metadata. in filters. Values may be any JSON value. ###### `items[].path` **string · required** Case-sensitive path within the collection, such as /reports/incident.txt. Start with / and omit a trailing /. Maximum 1,024 UTF-8 bytes. Empty, dot, parent, and control-character segments are invalid. ###### `items[].source` **object · required** Source metadata. Inline text is never returned. Its bytes field is the UTF-8 length of the submitted text. ###### `items[].source.bytes` **integer · optional · nullable** Declared size for URI and upload sources, or measured UTF-8 size for inline text. Omitted when no size is known. ###### `items[].source.checksum` **string · optional · nullable** Optional source checksum: sha256:, md5:, or crc32c: followed by lowercase hexadecimal digits. A mismatch fails processing with source_mismatch. ###### `items[].source.content_type` **string · required** MIME type of the file, such as text/plain, application/pdf, or video/mp4. ###### `items[].source.type` **string · required** How the file was supplied: URI pointer, upload, or inline text. - `uri`: A storage URI source. - `upload`: A separately uploaded source. - `inline`: Text submitted in the add request. ###### `items[].source.uri` **string · optional · nullable** Original storage URI. Present for URI sources. It is distinct from the file’s logical path. ###### `items[].status` **string · required** Current processing state. Only ready files contribute new indexed content to retrieval. - `pending`: Waiting for bytes or processing. - `indexing`: Building searchable content. - `ready`: Available for retrieval. - `failed`: Processing failed. Inspect error. - `deleting`: Removal and cleanup are in progress. ###### `items[].updated_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ##### `next_cursor` **string · required · nullable** Token for the next page, or null when this result has no next page. Do not parse or modify the token. ## Errors [Error format and retry guidance](/engine/reference/errors.md). ### 400 · `invalid_request` A field, path, parameter, or conditional request rule is invalid. Correct the request. Unknown fields are rejected. ```json { "error": { "code": "invalid_request", "message": "A field, path, parameter, or conditional request rule is invalid.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 400 · `invalid_cursor` The cursor expired or does not belong to this request and key. Restart from the first page. Preserve the same key, filters, and request values when continuing. ```json { "error": { "code": "invalid_cursor", "message": "The cursor expired or does not belong to this request and key.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 401 · `unauthenticated` The API key is missing, invalid, or revoked. Send an active key in Authorization: Bearer or X-API-Key. ```json { "error": { "code": "unauthenticated", "message": "The API key is missing, invalid, or revoked.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 403 · `forbidden` The key can see the resource but lacks permission for this operation. Use a key with the required action or scope kind. ```json { "error": { "code": "forbidden", "message": "The key can see the resource but lacks permission for this operation.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 404 · `not_found` The resource is absent, deleted, or outside this key’s scope. Check the identifier and the key’s namespace and collection scope. ```json { "error": { "code": "not_found", "message": "The resource is absent, deleted, or outside this key’s scope.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 503 · `temporarily_unavailable` A dependency, cluster readiness condition, or capacity limit prevents this operation. Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write. ```json { "error": { "code": "temporarily_unavailable", "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 500 · `internal_error` An unexpected server failure prevented this request from completing. Retain x-request-id for investigation. Follow retryable before retrying a write. ```json { "error": { "code": "internal_error", "message": "An unexpected server failure prevented this request from completing.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ## Other request languages ### cURL ```bash curl -sS "$GRAPHON_ENGINE_URL/namespaces/acme/collections/incident-logs/files" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections/incident-logs/files", headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], }, method="GET", ) with urllib.request.urlopen(request) as response: print(response.read().decode()) ``` ### JavaScript ```javascript const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/namespaces/acme/collections/incident-logs/files", { method: "GET", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, }, }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.