--- title: Get metadata fields description: List the file metadata fields that filters can read, with their type and state. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Get metadata fields `GET /namespaces/{namespace}/collections/{collection}/metadata-fields` List the file metadata fields that filters can read, with their type and state. **Permission:** Cluster key, or a scoped key with read (write includes read). [API key types and authentication](/engine/reference/authentication.md). A metadata key that is not listed is stored and returned with the file, but no filter can read it. status is indexing while the index is rebuilt for a change of that field. Filters read the old index until then. invalid_values is at least the number of stored values that do not fit the field type, read from a sample of the files already indexed. No filter matches those values. ## Example request ```http GET /namespaces/acme/collections/incident-logs/metadata-fields 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. ## Responses ### 200 · Success The requested resource or result. Content type: `application/json`. #### Response headers ##### `x-engine-request-id` **string · required** The Engine request ID. Retain it when investigating a failed or unexpected request. ##### `x-request-id` **string · required** The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID. ```json { "fields": { "environment": { "type": "text", "status": "ready", "invalid_values": 0 }, "severity": { "type": "number", "status": "indexing", "invalid_values": 0 } } } ``` #### Response fields ##### `fields` **map · required** Map of metadata key to the field. Only these keys can be used in a filter. ###### `fields[key].invalid_values` **integer · required** At least this many stored values do not fit the type, counted on a sample of the indexed files. They are stored, but no filter matches them. ###### `fields[key].status` **string · required** ready, or indexing while the index of this field is rebuilt after a change. - `ready`: Filters read the current index of this field. - `indexing`: The index of this field is being rebuilt. Filters read the old index. ###### `fields[key].type` **string · required** How filters read the values of this field. - `text`: Text. A number or a boolean is read as its JSON text. Compares in byte order. - `number`: A number, or a string that holds a plain decimal number. - `time`: An RFC 3339 date or date-time. Compares instants, so time zone offsets count. - `bool`: true or false, or the string "true" or "false". ## 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 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/metadata-fields" \ -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/metadata-fields", 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/metadata-fields", { 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.