Skip to main content
GET
This endpoint returns the connected subgraph of one ingested item: every item reachable from it through item-level relations, traversed breadth-first up to depth hops, together with the relations among those members and the structural graph around them (entities, comments, attachments, people). It answers a different question from Inspecting Context Relations. Relations are the entity-and-predicate triplets extracted from text (PaymentsWorker → depends_on → OrdersDB). The subgraph is about items: which Slack message replies to which, which page links to which, which ticket a comment belongs to. Use it after Query or List Documents when a single result is not enough and you need what surrounds it.
The Python and TypeScript SDKs gain context.subgraph() with their next release, generated from this spec. Until then call the endpoint directly as above; the CLI and the MCP server already do.

​
Path parameters

​
Query parameters

​
How items connect

Every member except the start item records how the traversal found it:
  • discovered_relation names the mechanism. It is same_thread when the member shares a thread with an item already in the subgraph (Slack replies, ticket comments); parent or child for a hierarchy tie (a comment and the message it is under, a page and its section); or the relation type of an explicit relates_to link declared at ingest (reply_to, references, whatever the ingest named it).
  • discovered_via is the source_id of the already-admitted member this one was first reached from. Follow it back and you rebuild the traversal tree: which reply hangs off which message, which page led to which.
Traversal is breadth-first, so depth on each member is its distance from the start item. The start item itself is a member at depth 0, with neither field set.

​
Reading the response

  • sources[] are the members, the start item included at depth: 0. Every source_id is an id you can pass to Fetch Content for the full document, or back to this endpoint to re-centre the subgraph on it. discovered_via on each member is another member’s source_id, so the list is also a tree.
  • relations[] are the item-level relations among the members (relates_to, same_thread, parent_of), in the same triplet shape as Inspecting Context Relations. Their endpoints are SOURCE entities whose entity_id is the item’s id.
  • auxiliary_relations[] is the structural graph around the members: which person sent a message, which entities are mentioned in it, which comments and attachments hang off it. These are recorded from the item itself, not extracted from text, so their context is empty.
  • Not included: the chunk-level entity relations that Query returns as graph_context. Those are a different read.

​
Some additional notes

An unknown id is an empty subgraph, not an error. The endpoint does not confirm or deny that an item exists; the same answer comes back for an id that was never ingested and for one the acl principals may not see.
  • An item nothing links to comes back as a one-member subgraph: itself, at depth 0, with max_depth_reached: 0. That is a real answer (“this stands alone”), distinct from an unknown id, which has no members.
  • Bounding the traversal. Threads and hierarchies can be large. depth bounds how far the walk goes; max_sources bounds how many members it returns. When max_sources clips it, is_truncated is true and the members you have are the ones closest to the start item. auxiliary_truncated reports the same for the structural graph.
  • Knowledge vs memory. If the id belongs to a memory, set type=memory; the two graphs never connect to each other.
  • Completeness. An item’s links populate once its indexing_status reaches completed. Items still in graph_creation may appear with fewer connections than they will have.
  • Cost. One request fans out into a bounded series of graph reads, so it is rate-limited like a Query, not like a status poll.
Related Resources

Authorizations

​
Authorization
string
header
required

API key sent as a Bearer token: "Bearer prefix.secret"

Path Parameters

​
id
string
required

Item ID: the ingested item whose connected subgraph to return. URL-encode it. An id containing a literal '/' cannot be spelled as one path segment; address those with the query form, GET /context/subgraph?id=.

Example:

"HydraDoc1234"

Query Parameters

​
database
string
required

Database (canonical name for the tenant scope)

Example:

"acme_corp"

​
collection
string

Collection (canonical name for the sub-tenant scope)

Example:

"team_docs"

​
tenant_id
string
deprecated

Deprecated alias for database

Example:

"tenant_1234"

​
sub_tenant_id
string
deprecated

Deprecated alias for collection

Example:

"sub_tenant_4567"

​
type
enum<string>
default:knowledge

Corpus type: 'knowledge' or 'memory'

Available options:
knowledge,
memory
​
depth
integer
default:5

Max traversal depth in hops

Required range: 1 <= x <= 10
​
max_sources
integer
default:200

Max members returned; is_truncated reports when this clipped the traversal

Required range: 1 <= x <= 1000
​
acl
string[]

Principals to answer as (document ACLs): the subgraph contains only items they may see, filtered at every hop. Repeated (acl=a&acl=b) or comma-separated. Omit for no ACL scoping.

Response

OK

​
data
object
Example:
​
error
object

Error message, empty string on success.

Example:
​
meta
object
Example:
​
success
boolean

Whether the request succeeded.

Example:

true