--- title: Get file description: Read one file’s source metadata and processing state. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Get file `GET /namespaces/{namespace}/collections/{collection}/files/{file}` Read one file’s source metadata and processing state. **Permission:** Cluster key, or a scoped key with read (write includes read). [API key types and authentication](/engine/reference/authentication.md). Use a fil_ ID, or encode a logical path as one URL segment. For simpler exact-path lookup, use the file list’s path parameter. This response contains file metadata, not file bytes. ## Example request ```http GET /namespaces/acme/collections/incident-logs/files/fil_01K6Q6N7D8E9F0G1H2J3K4M5N6 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. ### `file` **string · required** File ID with the fil_ prefix, or a file path encoded as one URL segment. Encode each / as %2F. Exact path lookup is also available with GET files?path=. ## Responses ### 200 · Success The requested resource or result. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ```json { "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" } ``` #### Response fields ##### `created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `error` **object · optional · nullable** Processing failure details. Omitted when the file has no error. ###### `error.code` **string · required** Machine-readable reason for the failure. Use this value for program logic and message for display or diagnostics. ###### `error.message` **string · required** Human-readable explanation of the failure. Do not parse this text to decide how to retry. ##### `governing_rule` **object · optional · nullable** Rule that governs retrieval of this file. Present only when the collection enforces access rules. ###### `governing_rule.file` **string · optional · nullable** Exact file target of the governing rule. Omitted for a folder rule. ###### `governing_rule.folder` **string · optional · nullable** Folder prefix of the governing rule. Omitted for a file rule. ###### `governing_rule.id` **string · required** Immutable ID of the rule that governs this file. ##### `id` **string · required** Immutable file ID with the fil_ prefix. Retain this ID from the add response. ##### `metadata` **map · required** Application data attached to the file, as a JSON object. Use metadata. in filters. Values may be any JSON value. ##### `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. ##### `source` **object · required** Source metadata. Inline text is never returned. Its bytes field is the UTF-8 length of the submitted text. ###### `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. ###### `source.checksum` **string · optional · nullable** Optional source checksum: sha256:, md5:, or crc32c: followed by lowercase hexadecimal digits. A mismatch fails processing with source_mismatch. ###### `source.content_type` **string · required** MIME type of the file, such as text/plain, application/pdf, or video/mp4. ###### `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. ###### `source.uri` **string · optional · nullable** Original storage URI. Present for URI sources. It is distinct from the file’s logical path. ##### `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. ##### `updated_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ## 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": {} } } ``` ### 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/fil_01K6Q6N7D8E9F0G1H2J3K4M5N6" \ -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/fil_01K6Q6N7D8E9F0G1H2J3K4M5N6", 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/fil_01K6Q6N7D8E9F0G1H2J3K4M5N6", { 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.