> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # kg_info > Return snapshot metadata for the workspace knowledge graph. **Cost class: cacheable.** Returns type distributions, totals, and the highest-degree hub nodes for the graph built at ingestion. ``snapshot_id`` is the cache key: it changes when the graph is rebuilt, so a caller can detect staleness cheaply. ``hubs`` are good ``kg_walk`` entry points when no specific node IDs are known. When ``path_prefix`` is supplied, counts are scoped to files under that prefix. Omitting it returns workspace-wide totals. ``include_graph`` adds a drawable sample: the backbone of the largest connected components, the edges among the sampled nodes, and the component statistics that say what the sample left out. It is for visual clients; a caller choosing walk seeds wants ``hubs``, which cost nothing. Call this before ``kg_search`` or ``kg_walk`` to confirm the graph exists and to select useful start nodes. ## OpenAPI ````yaml /openapi.json get /v1/workspaces/{workspace_id}/tools/kg-info openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}/tools/kg-info: get: tags: - tools summary: kg_info description: >- Return snapshot metadata for the workspace knowledge graph. **Cost class: cacheable.** Returns type distributions, totals, and the highest-degree hub nodes for the graph built at ingestion. ``snapshot_id`` is the cache key: it changes when the graph is rebuilt, so a caller can detect staleness cheaply. ``hubs`` are good ``kg_walk`` entry points when no specific node IDs are known. When ``path_prefix`` is supplied, counts are scoped to files under that prefix. Omitting it returns workspace-wide totals. ``include_graph`` adds a drawable sample: the backbone of the largest connected components, the edges among the sampled nodes, and the component statistics that say what the sample left out. It is for visual clients; a caller choosing walk seeds wants ``hubs``, which cost nothing. Call this before ``kg_search`` or ``kg_walk`` to confirm the graph exists and to select useful start nodes. operationId: kg_info_v1_workspaces__workspace_id__tools_kg_info_get parameters: - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string - description: Scope node and edge counts to files under this prefix. in: query name: path_prefix required: false schema: anyOf: - type: string - type: 'null' description: Scope node and edge counts to files under this prefix. title: Path Prefix - description: >- Also return a drawable subgraph in `graph`: a representative sample of nodes and the edges among them, for a client that renders the graph. Off by default — the sample is far larger than the counts, and a caller that draws nothing has no use for it. in: query name: include_graph required: false schema: default: false description: >- Also return a drawable subgraph in `graph`: a representative sample of nodes and the edges among them, for a client that renders the graph. Off by default — the sample is far larger than the counts, and a caller that draws nothing has no use for it. title: Include Graph type: boolean - description: >- Node budget for the `include_graph` sample. Ignored when `include_graph` is false. in: query name: graph_nodes required: false schema: default: 150 description: >- Node budget for the `include_graph` sample. Ignored when `include_graph` is false. maximum: 500 minimum: 1 title: Graph Nodes type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/KgInfo' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: KgInfo: additionalProperties: false description: >- Snapshot metadata for the knowledge graph, optionally scoped to a path prefix. ``snapshot_id`` is the cache key: it changes when the graph is rebuilt, so a caller can detect staleness without re-fetching everything. ``hubs`` are the highest-degree nodes *among those a walk can actually expand from* — useful entry points for an initial walk. A node above ``kg-walk``'s hub-degree cap is excluded here even if it outranks every hub shown: it is never a corridor, so seeding a walk on it would return only the seed. properties: built_at: format: date-time title: Built At type: string coverage: $ref: '#/components/schemas/Coverage' edge_total: title: Edge Total type: integer edge_types: items: $ref: '#/components/schemas/TypeCount' title: Edge Types type: array graph: anyOf: - $ref: '#/components/schemas/KgGraphSample' - type: 'null' hubs: items: $ref: '#/components/schemas/GraphNodeRef' title: Hubs type: array node_total: title: Node Total type: integer node_types: items: $ref: '#/components/schemas/TypeCount' title: Node Types type: array path_prefix: anyOf: - type: string - type: 'null' title: Path Prefix snapshot_id: title: Snapshot Id type: string required: - snapshot_id - built_at - node_types - edge_types - node_total - edge_total - hubs - path_prefix - coverage title: KgInfo type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object Coverage: additionalProperties: false description: >- What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. properties: labels_required: description: Which labels would have been needed to see the withheld candidates. items: type: string title: Labels Required type: array request_access_hint: anyOf: - type: string - type: 'null' title: Request Access Hint restricted_candidates: default: 0 title: Restricted Candidates type: integer title: Coverage type: object TypeCount: additionalProperties: false description: Count of a single node or edge type in the knowledge graph. properties: count: title: Count type: integer type: title: Type type: string required: - type - count title: TypeCount type: object KgGraphSample: additionalProperties: false description: >- A subgraph small enough to draw, plus the shape of the graph it came from. Sampling is the point: a real workspace graph has far more nodes than a node-link diagram can carry, so this is a *representative* slice — the backbone of the largest components — never the whole graph. Everything the slice cannot show is reported as a number beside it (``sampled_from``, ``component_total``, ``isolated_nodes``), so the picture is never mistaken for the census. properties: component_total: title: Component Total type: integer components: items: $ref: '#/components/schemas/GraphComponent' title: Components type: array edges: items: $ref: '#/components/schemas/GraphSampleEdge' title: Edges type: array isolated_nodes: title: Isolated Nodes type: integer nodes: items: $ref: '#/components/schemas/GraphSampleNode' title: Nodes type: array sampled_from: title: Sampled From type: integer truncated: title: Truncated type: boolean required: - nodes - edges - sampled_from - truncated - components - component_total - isolated_nodes title: KgGraphSample type: object GraphNodeRef: additionalProperties: false description: Lightweight reference to a graph node, used in hub listings. properties: degree: title: Degree type: integer node_id: title: Node Id type: string node_type: title: Node Type type: string title: title: Title type: string required: - node_id - node_type - title - degree title: GraphNodeRef type: object Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: description: Per-request correlation id; matches the ``X-Request-Id`` header. title: Request Id type: string retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable - request_id title: Error type: object GraphComponent: additionalProperties: false description: >- A group the sampled nodes belong to: one connected component, or the orphans. ``size`` counts the group in the whole caller-visible slice, ``sampled`` how many of it the drawing shows. Every isolated node shares a single group — one row per orphan would drown the components that carry structure, and they are individually identical anyway — flagged by ``isolated``. properties: isolated: default: false title: Isolated type: boolean sampled: title: Sampled type: integer size: title: Size type: integer required: - size - sampled title: GraphComponent type: object GraphSampleEdge: additionalProperties: false description: >- One relation of the drawable subgraph, collapsed across its restatements. The canonical edge key includes the source file, so a relation asserted by three documents is three rows in the store. Drawing them as three parallel lines says nothing ``statements`` does not say better, so they arrive here as one edge carrying the count. properties: edge_type: title: Edge Type type: string from_node_id: title: From Node Id type: string statements: title: Statements type: integer to_node_id: title: To Node Id type: string required: - from_node_id - to_node_id - edge_type - statements title: GraphSampleEdge type: object GraphSampleNode: additionalProperties: false description: One node of the drawable subgraph ``kg-info`` samples on request. properties: component: title: Component type: integer degree: title: Degree type: integer is_document: title: Is Document type: boolean node_id: title: Node Id type: string node_type: title: Node Type type: string source_file_count: title: Source File Count type: integer title: title: Title type: string required: - node_id - node_type - title - degree - source_file_count - is_document - component title: GraphSampleNode type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - session_busy - range_not_satisfiable - result_expired - access_denied - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````