Inspecting Context Relations

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

const relations = await client.context.relations({
  database: "acme_corp",
  id: "billing_runbook_v3",
  limit: 500,
});

curl -G 'https://api.hydradb.com/context/relations' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "id=billing_runbook_v3" \
  --data-urlencode "limit=500"

{
  "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
  }
}

{
  "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 depends on OrdersDB for transaction sync.",
            "confidence": 0.88,
            "temporal_details": null,
            "timestamp": "2026-05-12T08:14:00Z",
            "relationship_id": "rel_payments_orders",
            "chunk_id": "policy_main_chunk_4",
            "source_entity_id": "entity_payments_worker",
            "target_entity_id": "entity_orders_db"
          }
        ],
        "chunk_id": "policy_main_chunk_4"
      }
    ],
    "auxiliary_relations": [],
    "auxiliary_truncated": false,
    "is_truncated": true,
    "next_cursor": 1778573640.0,
    "success": true,
    "message": "Successfully fetched relations for source"
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database 'acme_corp' not found. Use GET /databases to list active databases."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

GET

context

relations

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

const relations = await client.context.relations({
  database: "acme_corp",
  id: "billing_runbook_v3",
  limit: 500,
});

curl -G 'https://api.hydradb.com/context/relations' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "id=billing_runbook_v3" \
  --data-urlencode "limit=500"

{
  "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
  }
}

{
  "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 depends on OrdersDB for transaction sync.",
            "confidence": 0.88,
            "temporal_details": null,
            "timestamp": "2026-05-12T08:14:00Z",
            "relationship_id": "rel_payments_orders",
            "chunk_id": "policy_main_chunk_4",
            "source_entity_id": "entity_payments_worker",
            "target_entity_id": "entity_orders_db"
          }
        ],
        "chunk_id": "policy_main_chunk_4"
      }
    ],
    "auxiliary_relations": [],
    "auxiliary_truncated": false,
    "is_truncated": true,
    "next_cursor": 1778573640.0,
    "success": true,
    "message": "Successfully fetched relations for source"
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database 'acme_corp' not found. Use GET /databases to list active databases."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

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.

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

const relations = await client.context.relations({
  database: "acme_corp",
  id: "billing_runbook_v3",
  limit: 500,
});

curl -G 'https://api.hydradb.com/context/relations' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "id=billing_runbook_v3" \
  --data-urlencode "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": 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
  }
}

{
  "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 depends on OrdersDB for transaction sync.",
            "confidence": 0.88,
            "temporal_details": null,
            "timestamp": "2026-05-12T08:14:00Z",
            "relationship_id": "rel_payments_orders",
            "chunk_id": "policy_main_chunk_4",
            "source_entity_id": "entity_payments_worker",
            "target_entity_id": "entity_orders_db"
          }
        ],
        "chunk_id": "policy_main_chunk_4"
      }
    ],
    "auxiliary_relations": [],
    "auxiliary_truncated": false,
    "is_truncated": true,
    "next_cursor": 1778573640.0,
    "success": true,
    "message": "Successfully fetched relations for source"
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database 'acme_corp' not found. Use GET /databases to list active databases."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

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"

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

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

Start here

Databases

Context

Query

Connectors

Webhooks

Reference

Inspecting Context Relations

Query parameters

Notes

Errors

Authorizations

Query Parameters

Response

​Query parameters

​Pagination pattern

​Notes

​Errors

Authorizations

Query Parameters

Response

Query parameters

Pagination pattern

Notes

Errors