Inspecting Context Relations

Read the entity-relation triplets extracted from your content, for one source or a whole collection.

GET /context/relations

Python SDK

relations = client.context.relations(
    database="acme_corp",
    id="billing_runbook_v3",
    limit=500,
)

Success

{
  "success": true,
  "data": {
    "relations": [
      {
        "source": {
          "name": "PaymentsWorker",
          "type": "Service",
          "namespace": "default",
          "entity_id": "entity_payments_worker",
          "identifier": null,
          "provider": ""
        },
        "target": {
          "name": "OrdersDB",
          "type": "Database",
          "namespace": "default",
          "entity_id": "entity_orders_db",
          "identifier": null,
          "provider": ""
        },
        "relations": [
          {
            "canonical_predicate": "DEPENDS_ON",
            "raw_predicate": "depends on",
            "context": "PaymentsWorker fetches transactions from OrdersDB during sync.",
            "confidence": 0.93,
            "temporal_details": "2026-02",
            "timestamp": "2026-05-12T08:14:00Z",
            "relationship_id": "rel_payments_orders",
            "chunk_id": "policy_main_chunk_3",
            "source_entity_id": "entity_payments_worker",
            "target_entity_id": "entity_orders_db"
          }
        ],
        "chunk_id": "policy_main_chunk_3"
      }
    ],
    "auxiliary_relations": [],
    "auxiliary_truncated": false,
    "is_truncated": false,
    "next_cursor": null,
    "success": true,
    "message": "Successfully fetched relations for source"
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Inspect relationships extracted from your content, such as PaymentsWorker depends on OrdersDB. Each three-part relationship is a triplet: a starting entity (a named person, service, or topic), a relationship, and a target entity.

Pass id to scope to a single ingested item, or omit it to return all relations in the collection. Set type=memory to inspect a memory’s relations. Pagination handles large result sets.

Python SDK

relations = client.context.relations(
    database="acme_corp",
    id="billing_runbook_v3",
    limit=500,
)

Query parameters

Name	Description
	Owning database. Formerly tenant_id; the tenant_id alias is still accepted (deprecated).
	When provided, returns relations for that specific source. When omitted, returns all relations across the collection. (default=null)
	Bucket selector. Use "memory" when id belongs to a memory item. (default="knowledge")
	Collection scope. If omitted, the default collection is used. Formerly sub_tenant_id; the sub_tenant_id alias is still accepted (deprecated). (default=null)
	Maximum relation groups to return. Range 1 to 10000. (default=5000)
	Opaque pagination cursor from a previous response’s next_cursor. (default=null)
	Principals to answer as (document ACLs). Only relations from sources those principals may see are returned. Repeated (acl=a&acl=b) or comma-separated. Omit for no ACL scoping. See Access Control.

Success

{
  "success": true,
  "data": {
    "relations": [
      {
        "source": {
          "name": "PaymentsWorker",
          "type": "Service",
          "namespace": "default",
          "entity_id": "entity_payments_worker",
          "identifier": null,
          "provider": ""
        },
        "target": {
          "name": "OrdersDB",
          "type": "Database",
          "namespace": "default",
          "entity_id": "entity_orders_db",
          "identifier": null,
          "provider": ""
        },
        "relations": [
          {
            "canonical_predicate": "DEPENDS_ON",
            "raw_predicate": "depends on",
            "context": "PaymentsWorker fetches transactions from OrdersDB during sync.",
            "confidence": 0.93,
            "temporal_details": "2026-02",
            "timestamp": "2026-05-12T08:14:00Z",
            "relationship_id": "rel_payments_orders",
            "chunk_id": "policy_main_chunk_3",
            "source_entity_id": "entity_payments_worker",
            "target_entity_id": "entity_orders_db"
          }
        ],
        "chunk_id": "policy_main_chunk_3"
      }
    ],
    "auxiliary_relations": [],
    "auxiliary_truncated": false,
    "is_truncated": false,
    "next_cursor": null,
    "success": true,
    "message": "Successfully fetched relations for source"
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Pagination pattern

all_relations = []
cursor = None

while True:
    page = client.context.relations(
        database="acme_corp",
        id="billing_runbook_v3",
        limit=1000,
        cursor=cursor,
    )
    all_relations.extend(page.relations)
    if page.next_cursor is None:
        break
    cursor = page.next_cursor

Notes

Cursor opacity: next_cursor is opaque (currently the timestamp, in Unix seconds, of the last group returned). Don’t construct it client-side or assume meaning: pass back exactly what the server returned.

• Full-graph exports: omit id, use a small limit, and paginate.
• Ordering: data.relations[] comes back newest first, by each group’s latest relation timestamp, not by relevance.
• Unknown id: returns 200 with an empty relations list, not an error. So does an id the acl principals may not see.
• auxiliary_relations: the structural graph around the sources (who sent a message, which comments hang off it), in the same triplet shape. It does not count against limit; auxiliary_truncated is true when it was clipped.
• Graph completeness: Source relations only fully populate once the source’s indexing_status reaches completed. Items in graph_creation are searchable but their relations may still be in flight.
• timestamp format differs by endpoint: On this endpoint each relation’s timestamp is an ISO-8601 string (e.g. 2026-05-12T08:14:00Z). The same relations surfaced as passthrough on Query (in graph_context) and List Documents carry timestamp as a Unix epoch float (seconds) instead. Normalize before comparing relation timestamps across endpoints.

Errors

Common codes: 400 INVALID_INPUT (missing database, a limit outside 1 to 10000, or a non-numeric cursor), 404 DATABASE_NOT_FOUND, 500 INTERNAL_ERROR (a transient graph read failure; retry the request). See Error Responses for the full list.

Related Resources

• Indexing status: Ingestion Status, to confirm the graph is complete
• Query with graph context: Query with graph_context: true
• Concepts: Concepts: Context Graphs

Authorizations

Authorization · string · header · required

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

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"

id · string

Source ID (omit for database-wide relations)

Example:

"HydraDoc1234"

type · enum<string>

Corpus type: 'knowledge' or 'memory'

Available options: knowledge, memory

limit · integer · default: 5000

Max relations to return

cursor · number

Pagination cursor

acl · string[]

Principals to answer as (PRO-1684 document ACLs): only relations attributable to sources they may see are returned. Repeated (acl=a&acl=b) or comma-separated. Omit for no ACL scoping.

Response

200

application/json

OK

data · object

Show child attributes

Example:

{
  "auxiliary_relations": [
    {
      "chunk_id": "HydraEmbeddings123_0",
      "relations": [
        {
          "canonical_predicate": "works_at",
          "chunk_id": "HydraEmbeddings123_0",
          "confidence": 0.92,
          "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
          "raw_predicate": "is employed by",
          "relationship_id": "rel_1234",
          "source_entity_id": "entity_1a2b",
          "synthesized": true,
          "target_entity_id": "entity_3c4d",
          "temporal_details": "since 2024",
          "timestamp": "2026-07-02T10:00:00Z"
        }
      ],
      "source": {
        "entity_id": "entity_1a2b",
        "identifier": "Acme Corp",
        "name": "general",
        "namespace": "organization",
        "provider": "slack",
        "type": "knowledge"
      },
      "target": {
        "entity_id": "entity_1a2b",
        "identifier": "Acme Corp",
        "name": "general",
        "namespace": "organization",
        "provider": "slack",
        "type": "knowledge"
      },
      "truncated": true
    }
  ],
  "auxiliary_truncated": true,
  "is_truncated": false,
  "message": "Success",
  "next_cursor": 0.5,
  "relations": [
    {
      "chunk_id": "HydraEmbeddings123_0",
      "relations": [
        {
          "canonical_predicate": "works_at",
          "chunk_id": "HydraEmbeddings123_0",
          "confidence": 0.92,
          "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
          "raw_predicate": "is employed by",
          "relationship_id": "rel_1234",
          "source_entity_id": "entity_1a2b",
          "synthesized": true,
          "target_entity_id": "entity_3c4d",
          "temporal_details": "since 2024",
          "timestamp": "2026-07-02T10:00:00Z"
        }
      ],
      "source": {
        "entity_id": "entity_1a2b",
        "identifier": "Acme Corp",
        "name": "general",
        "namespace": "organization",
        "provider": "slack",
        "type": "knowledge"
      },
      "target": {
        "entity_id": "entity_1a2b",
        "identifier": "Acme Corp",
        "name": "general",
        "namespace": "organization",
        "provider": "slack",
        "type": "knowledge"
      },
      "truncated": true
    }
  ],
  "success": true
}

error · object | null

Null on success; an object with code and message on failure.

Show child attributes

Example:

null

meta · object

Show child attributes

Example:

{
  "collection": "team_docs",
  "database": "acme_corp",
  "latency_ms": 12.3,
  "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
  "source_type": "file",
  "sub_tenant_id": "team_docs",
  "tenant_id": "acme_corp"
}

success · boolean

Whether the request succeeded.

Example:

true