Visualization payloads

visualize_graph() renders a self-contained HTML page. The functions on this page return the same data as plain dictionaries instead, so an external UI or dashboard can render it itself. Both paths run through the same authorized, bounded graph read and the same preprocess() step, so they cannot drift on the data — only on how each packages it.

These builders are not re-exported on the top-level cognee module. Import them from cognee.api.v1.visualize.

from cognee.api.v1.visualize import (
    visualize_graph_json,
    visualize_semantic_json,
    build_brains_payload,
    build_brains_summary_payload,
    get_live_events,
    get_memory_provenance_payload,
    stream_dataset_updates,
)

visualize_graph_json()

async def visualize_graph_json(
    include_session_events: bool = True,
    session_ids: list = None,
    user: Optional[User] = None,
    dataset: Optional[Union[str, UUID]] = "main_dataset",
    *,
    full: bool = False,
    query: Optional[str] = None,
    seed_node_ids: Optional[List[str]] = None,
    recall_result: Optional[Any] = None,
    neighborhood_depth: int = 2,
    neighborhood_seed_top_k: int = 10,
    max_nodes: int = 500,
) -> dict

The graph as a JSON-safe dict, without the semantic layout. Authorization, dataset resolution and the bounded fetch are shared with visualize_graph(), so the same arguments give you exactly the subgraph the HTML page would have shown — including the bounded-subgraph defaults.

Parameters

bool

default:"True"

Embed the caller’s search and improve events in the payload as search_events, scoped to dataset. Sessions attributed to no dataset are not included.

list

default:"None"

Restrict embedded session events to these sessions. An explicit list is an intentional override, used as given and not narrowed to dataset.

Optional[User]

default:"None"

User context for dataset access. Falls back to the default user.

Optional[Union[str, UUID]]

default:"'main_dataset'"

Dataset name or id to read.

bool

default:"False"

Return the entire graph instead of a bounded subgraph.

Optional[str]

default:"None"

Query string whose nearest vector hits seed the subgraph.

Optional[List[str]]

default:"None"

Explicit seed node ids for neighborhood expansion.

Optional[Any]

default:"None"

A recall() or search result whose graph provenance seeds the subgraph. Python-only — there is no HTTP equivalent.

int

default:"2"

k-hop expansion depth around the seeds.

int

default:"10"

Maximum number of seed nodes.

int

default:"500"

Hard cap on nodes after expansion.

Returns

dict — every field of the renderer’s PreprocessedGraph snapshot, plus search_events:

Key	Contents
`nodes`, `links`	The graph itself, with per-node render metadata.
`color_maps`	Color assignments, keyed by `type` and `node_set`.
`schema_graph`, `schema_data`	The type-level view behind the Schema tab.
`memory_map`	The pipeline-structure view behind the Memory tab.
`pipeline_stages`, `edge_classes`, `bundles`, `provenance_index`, `has_meaningful_topological_rank`	Derived values the bundled renderer reads directly; a client replacing those modules needs them.
`search_events`	The caller’s search and improve events for `dataset`, or `[]`.

Semantic positions are deliberately absent — see below.

payload = await visualize_graph_json(query="natural language processing")
print(len(payload["nodes"]), len(payload["links"]))

visualize_semantic_json()

async def visualize_semantic_json(
    user: Optional[User] = None,
    dataset: Optional[Union[str, UUID]] = "main_dataset",
    *,
    full: bool = False,
    query: Optional[str] = None,
    seed_node_ids: Optional[List[str]] = None,
    recall_result: Optional[Any] = None,
    neighborhood_depth: int = 2,
    neighborhood_seed_top_k: int = 10,
    max_nodes: int = 500,
) -> dict

Semantic positions and clusters for the same subgraph, computed on demand. Pass the same dataset/seed/depth/cap arguments you passed to visualize_graph_json() to lay out the same subgraph. This is the one call that fetches embeddings and runs the PCA (or UMAP) projection over them, bounded to SEMANTIC_NODE_CAP = 2000 nodes. The HTML render computes the layout on every render; splitting it out here means a client that never opens a semantic view never pays for it.

Returns

dict with semantic_positions and semantic_clusters. Both are null together — the layout is best-effort, so no embeddings resolving or the projection failing yields {"semantic_positions": null, "semantic_clusters": null} rather than an error.

build_brains_payload()

async def build_brains_payload(
    user: Optional[User] = None,
    max_nodes: int = 500,
) -> dict

A small graph preview for every dataset the caller may read — their own, their tenant’s, and anything granted to a role they belong to. There is no dataset argument: this is the overview across brains, not one brain.

Returns

dict keyed by dataset id, each value {"name", "nodes", "links", "node_set_colors"} — not the full visualize_graph_json() shape, since an overview does not need one dataset’s worth of schema/memory/pipeline detail multiplied by every dataset. max_nodes is applied independently per dataset; there is no larger combined cap.

build_brains_summary_payload()

async def build_brains_summary_payload(
    user: Optional[User] = None,
) -> dict

The cheap counterpart of build_brains_payload(): the same datasets — the authorization union is shared, so both list exactly the same brains — but only what an overview shows (name, sources, size, colors), built from relational metadata and the per-cognify-run count cache instead of one bounded graph read per dataset. A cold cache pays one count query per cognify run whose count is not cached yet; every call after that pays no graph reads at all. Reach for build_brains_payload() only when the node and link arrays themselves are needed.

Returns

dict keyed by dataset id (as a string), each value {"name", "source_names", "node_count", "node_set_colors"}:

Key	Contents
`name`	The dataset’s name.
`source_names`	The dataset’s distinct node set names, sorted; empty when the data was ingested without node sets.
`node_count`	Nodes in the dataset’s graph as of its latest cognify run — the whole graph, not only entity nodes, and `0` for a dataset never cognified.
`node_set_colors`	Node set colors from the same rule `build_brains_payload()` uses. Same rule and same node sets give the same colors, but the two calls can be looking at different node sets — `/brains` reads them off its bounded graph fetch (and so sees sets that exist only in the graph, such as the memory sets `improve()` writes), this one reads them from the dataset’s relational rows — and where the sets differ the colors do too.

get_live_events()

async def get_live_events(
    dataset_id: UUID,
    since: Optional[datetime] = None,
    user: Optional[User] = None,
) -> Dict[str, Any]

The delta of search and improve events since a cursor, for refreshing a timeline without rebuilding the whole graph payload. dataset_id both gates and scopes. It gates with the same read-permission check every other visualization entry point runs, and it scopes the events: only the caller’s own sessions attributed to that dataset contribute, matching the search_events already embedded in visualize_graph_json() for the same dataset. A session attributed to no dataset — the plain global default_session an unscoped or cross-dataset search runs in — contributes to no dataset’s timeline, since it could belong to any dataset the caller has queried. Attribution is per session, not per answered turn: a session id reused across datasets stays with the first dataset it touched, so its later turns appear on that dataset’s timeline. Raises PermissionDeniedError when the dataset does not exist or the caller cannot read it.

Returns

{"events": [...], "cursor": <ISO datetime string or None>}. Omit since on the first call to get everything available, then pass the previous response’s cursor straight back as the next since — the filter is strict (>, not >=), so no event is delivered twice. When nothing new has happened the response echoes back the since you sent, or null if you sent none.

stream_dataset_updates()

async def stream_dataset_updates(
    websocket: WebSocket,
    dataset_id: UUID,
    user: User,
    since: Optional[datetime] = None,
) -> None

The push loop behind WS /api/v1/visualize/subscribe/{dataset_id} — sends a ready frame, then pushes live_events, graph_grew and heartbeat frames until the client disconnects, so a client can stop polling get_live_events() and refetching the graph payload entirely. See Live dataset updates for the frame shapes, cadences, and close codes. Exposed for deployments that mount their own WebSocket route. It expects an already accepted, already authorized connection — the caller owns accept and close, so a rejection can carry a close code the client will actually see — and raises PermissionDeniedError when read access to the dataset is lost while the stream is running (permission is re-checked on every poll).

get_memory_provenance_payload()

async def get_memory_provenance_payload(
    include_memory: bool = False,
    scope_tenant_ids: Optional[List[Any]] = None,
    scope_user_ids: Optional[List[Any]] = None,
) -> dict

The memory-provenance graph — the ownership and data-flow story read purely from the relational database — packaged as a dict. Same scoping rules as get_memory_provenance_graph(): in multi-tenant deployments you must pass a scope, or the read spans every tenant.

Returns

dict in the same shape visualize_graph_json() returns (nodes, links, color_maps, schema_graph, memory_map, and the rest) — not the raw (nodes, edges) tuple get_memory_provenance_graph() returns.

Over HTTP

Each builder above has an HTTP endpoint in front of it. GET /api/v1/visualize/json, GET /api/v1/visualize/semantic and GET /api/v1/schema/provenance/json are JSON siblings of existing HTML endpoints; /brains, /brains-summary and /live-events have no HTML equivalent. POST /api/v1/visualize/multi remains HTML-only, and stream_dataset_updates() fronts a WebSocket route rather than a GET.

Endpoint	Returns
`GET /api/v1/visualize/json`	`visualize_graph_json()`’s payload. No semantic layout.
`GET /api/v1/visualize/semantic`	`semantic_positions` and `semantic_clusters` for the same subgraph.
`GET /api/v1/visualize/brains`	`build_brains_payload()`’s per-dataset previews. Takes no `dataset_id` — only `max_nodes`.
`GET /api/v1/visualize/brains-summary`	`build_brains_summary_payload()`’s per-dataset overviews. Takes no parameters.
`GET /api/v1/visualize/live-events`	`{"events": [...], "cursor": ...}` for the caller’s session events attributed to `dataset_id`.
`WS /api/v1/visualize/subscribe/{dataset_id}`	`stream_dataset_updates()`’s frames, pushed instead of polled — see Live dataset updates. Takes an optional `since` reconnect cursor.
`GET /api/v1/schema/provenance/json`	`get_memory_provenance_payload()`’s payload, always scoped to the authenticated caller’s tenant (or user). Takes `include_memory`.

All of them require authentication. The routes that take a dataset_id enforce the same read permission as GET /api/v1/visualize; /brains and /brains-summary take none and simply return the datasets the caller can read. The WebSocket route also accepts the API key or bearer token as a ?token= query parameter, since a browser cannot set headers on a WebSocket handshake — mind that the handshake URL, query string included, shows up in the default access logs of common reverse proxies. /json and /semantic accept the same query params as GET /api/v1/visualize — dataset_id (required), full, query, seed_node_ids, neighborhood_depth, neighborhood_seed_top_k and max_nodes — with the defaults listed above. Pass identical arguments to both to get a graph and its semantic layout for the same subgraph.

curl "$COGNEE_URL/api/v1/visualize/json?dataset_id=$DATASET_ID&query=natural+language+processing"

{
  "nodes": [ ... ],
  "links": [ ... ],
  "color_maps": { "type": { ... }, "node_set": { ... } },
  "schema_graph": { "nodes": [ ... ], "links": [ ... ] },
  "memory_map": { ... },
  "search_events": []
}

Errors

JSON error bodies carry a fixed message and never the exception text — full detail is server-logged instead.

403 — /live-events only, when the caller lacks read permission on the dataset (or it does not exist).
409 — the payload could not be built. Note that a semantic layout that cannot be computed is not an error: /semantic answers 200 with both fields null, and only returns 409 if the underlying graph fetch itself fails.

The WebSocket route signals failure with close codes instead: 1008 when the caller is not authenticated or lacks read permission on the dataset (a retry replays the same rejection), 1011 when the stream failed server-side (reconnecting is reasonable).

Reference

Visualization Payloads

Visualization payloads

visualize_graph_json()

Parameters

Returns

visualize_semantic_json()

Returns

build_brains_payload()

Returns

build_brains_summary_payload()

Returns

get_live_events()

Returns

stream_dataset_updates()

get_memory_provenance_payload()

Returns

Over HTTP

Errors

See also

​Visualization payloads

​visualize_graph_json()

​Parameters

​Returns

​visualize_semantic_json()

​Returns

​build_brains_payload()

​Returns

​build_brains_summary_payload()

​Returns

​get_live_events()

​Returns

​stream_dataset_updates()

​get_memory_provenance_payload()

​Returns

​Over HTTP

​Errors

​See also

Visualization payloads

visualize_graph_json()

Parameters

Returns

visualize_semantic_json()

Returns

build_brains_payload()

Returns

build_brains_summary_payload()

Returns

get_live_events()

Returns

stream_dataset_updates()

get_memory_provenance_payload()

Returns

Over HTTP

Errors

See also