Get file

Read one file’s source metadata and processing state.

GET/namespaces/{namespace}/collections/{collection}/files/{file}

PermissionCluster key, or a scoped key with read (write includes read). Key scopes and actions.

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.

Request

https://engine.example.com/namespaces/acme/collections/incident-logs/files/fil_01K6Q6N7D8E9F0G1H2J3K4M5N6

GET /namespaces/acme/collections/incident-logs/files/fil_01K6Q6N7D8E9F0G1H2J3K4M5N6 HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

The requested resource or result.

{
  "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"
}

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

filestringrequired

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

200Success

The requested resource or result.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

created_atstring (date-time)required

Time the resource was created, as an ISO 8601 UTC timestamp.

errorobjectoptionalaccepts null

Processing failure details. Omitted when the file has no error.

governing_ruleobjectoptionalaccepts null

Rule that governs retrieval of this file. Present only when the collection enforces access rules.

idstringrequired

Immutable file ID with the fil_ prefix. Retain this ID from the add response.

metadatamap<string, JSON value>required

Application data attached to the file, as a JSON object. Values may be any JSON value. A filter can read metadata.<key> only when the collection lists that key in its metadata fields.

pathstringrequired

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.

sourceobjectrequired

Source metadata. Inline text is never returned. Its bytes field is the UTF-8 length of the submitted text.

stagestringoptionalaccepts null

Current step of an indexing file. Stages only move forward. Null for every other status.

engine_queued: Waiting for an Engine worker.
checking_source: Engine checks the source and sends it for processing.
core_queued: Waiting in the processing queue of the namespace.
processing: Engine reads and processes the content.
building_index: Processed. Waiting for an index that can serve the file.

statusstringrequired

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_atstring (date-time)required

Time the resource last changed, as an ISO 8601 UTC timestamp.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown