> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Graph Relations By Source ID
> Retrieve all entity relationships extracted from a single source.
## When to use it
* **Debugging graph construction** – verify HydraDB extracted the relationships you expected
* **Visualizations** – build entity graphs in admin UIs
* **Audit** – confirm what entities and connections exist for a specific document
This endpoint returns the raw triplets (subject → predicate → object) that HydraDB extracted from a single source.
## Endpoint
* **Auth:** Bearer token
* **Idempotency:** Read-only
* **Async:** No
## Example
```bash cURL theme={"dark"}
curl 'https://api.hydradb.com/list/graph_relations_by_id?source_id=doc_12345&tenant_id=my_first_tenant&limit=100' \
-H "Authorization: Bearer "
```
```typescript TypeScript SDK theme={"dark"}
const response = await client.fetch.graphRelationsBySourceId({
source_id: "doc_12345",
tenant_id: "my_first_tenant",
limit: 100
});
```
```python Python SDK theme={"dark"}
response = client.fetch.graph_relations_by_source_id(
source_id="doc_12345",
tenant_id="my_first_tenant",
limit=100,
)
```
## Query parameters
| Name | Type | Required | Default | Description |
| --------------- | ------- | --------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `source_id` | string | No (defaults to root) | – | The source to fetch relations for. Optional - if omitted, returns top-level entity relations. |
| `tenant_id` | string | Yes | – | The tenant the source belongs to. |
| `sub_tenant_id` | string | No | default | Sub-tenant scope. |
| `is_memory` | boolean | No | `false` | Set `true` to fetch relations for a memory; `false` for knowledge. |
| `limit` | integer | No | `250` | Maximum number of relations to return. |
## Response
```json theme={"dark"}
{
"success": true,
"message": "Relations retrieved successfully",
"relations": [
{
"source": {
"name": "Pricing Strategy",
"type": "PROJECT",
"entity_id": "ent_abc123",
"namespace": "default"
},
"target": {
"name": "Product Team",
"type": "ORGANIZATION",
"entity_id": "ent_def456",
"namespace": "default"
},
"relations": [
{
"canonical_predicate": "OWNED_BY",
"raw_predicate": "is owned by",
"context": "The Q4 pricing strategy was developed and is owned by the Product Team...",
"confidence": 0.92,
"relationship_id": "rel_xyz789",
"chunk_id": "chunk_001"
}
],
"chunk_id": "chunk_001"
}
]
}
```
| Field | Description |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `relations[]` | Array of triplets extracted from this source. |
| `relations[].source` | Subject entity. |
| `relations[].target` | Object entity. |
| `relations[].relations[]` | Evidence for the relationship. Multiple entries mean the same connection appears in multiple chunks. |
| `relations[].relations[].canonical_predicate` | Normalized relationship type (e.g., `OWNED_BY`, `REPORTS_TO`, `WORKS_FOR`). |
| `relations[].relations[].raw_predicate` | The original phrasing extracted from the text. |
| `relations[].relations[].context` | Surrounding context for the relationship. |
| `relations[].relations[].confidence` | Extraction confidence (0.0–1.0). |
| `relations[].chunk_id` | The chunk this triplet came from. |
## Entity types
The `type` field on each entity is normalized at extraction. Common types:
| Type | Examples |
| -------------- | ------------------------------- |
| `PERSON` | Named individuals |
| `ORGANIZATION` | Companies, teams, departments |
| `PROJECT` | Initiatives, products, releases |
| `PRODUCT` | Specific products or services |
| `ERROR_CODE` | Error identifiers |
| `LOCATION` | Geographic entities |
The full list depends on what HydraDB extracted from your specific content.
## Behavior notes
**No relations doesn't mean no graph.** A source might be successfully indexed without producing extractable triplets (very short content, structured data, or content without clear entity-relationship language). Use this endpoint to confirm what was actually extracted.
**Memories vs knowledge.** Set `is_memory: true` to look up relations for a memory item. The default (`false`) targets knowledge sources.
## Related endpoints
* **Browse sources first:** [List data](/api-reference/endpoint/list-data) – find the `source_id` you want to inspect
* **Retrieve content:** [Fetch content](/api-reference/endpoint/fetch-content) – get the original file or text
* **Use in recall:** [Full recall](/api-reference/endpoint/full-recall) with `graph_context: true` – see graph context applied to a query
## Errors
Common codes: `400 INVALID_PARAMETERS`, `404 SOURCE_NOT_FOUND`, `422 VALIDATION_ERROR`. See [Error Responses](/api-reference/error-responses) for the full list.
Read more: [Essentials → Context Graphs](/essentials/context-graphs)
## OpenAPI
````yaml GET /list/graph_relations_by_id
openapi: 3.1.0
info:
title: HydraDB API
description: REST APIs for the HydraDB retrieval engine
version: 0.0.1
servers:
- url: https://api.hydradb.com
description: Production
x-fern-server-name: hydradb-prod
security: []
paths:
/list/graph_relations_by_id:
get:
tags:
- list
summary: Graph Relations By Id
operationId: graph_relations_by_id_list_graph_relations_by_id_get
parameters:
- name: source_id
in: query
required: true
schema:
type: string
description: The source ID to fetch relations for
title: Source Id
example:
description: The source ID to fetch relations for
- name: tenant_id
in: query
required: false
schema:
type: string
description: Unique identifier for the tenant/organization
default: ''
title: Tenant Id
example: tenant_1234
description: Unique identifier for the tenant/organization
- name: is_memory
in: query
required: false
schema:
type: boolean
description: Whether to fetch relations for memories
default: false
title: Is Memory
example:
description: Whether to fetch relations for memories
- name: sub_tenant_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sub Tenant Id
description: >-
Optional sub-tenant identifier used to organize data within a
tenant. If omitted, the default sub-tenant created during tenant
setup will be used.
example: sub_tenant_4567
description: >-
Optional sub-tenant identifier used to organize data within a
tenant. If omitted, the default sub-tenant created during tenant
setup will be used.
- name: limit
in: query
required: false
schema:
type: integer
description: Maximum number of relations to return
default: 250
title: Limit
example:
description: Maximum number of relations to return
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SourceGraphRelationsResponse'
'400':
description: Bad Request - Invalid input parameters
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'401':
description: Unauthorized - Authentication required
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'403':
description: Forbidden - Access denied
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'404':
description: Not Found - Resource does not exist
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'422':
description: Unprocessable Entity - Validation failed
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
security:
- HTTPBearer: []
components:
schemas:
SourceGraphRelationsResponse:
properties:
relations:
items:
anyOf:
- $ref: '#/components/schemas/TripletWithEvidence'
- type: 'null'
type: array
title: Relations
description: List of relations retrieved
example: []
success:
type: boolean
title: Success
description: Indicates whether the request was successful
default: true
example: true
message:
type: string
title: Message
description: Response message describing the operation result
default: Relations retrieved successfully
type: object
required:
- relations
title: SourceGraphRelationsResponse
cortex__models__response__commons__ActualErrorResponse:
properties:
detail:
$ref: >-
#/components/schemas/cortex__models__response__commons__ErrorResponse
type: object
required:
- detail
title: ActualErrorResponse
TripletWithEvidence:
properties:
source:
$ref: '#/components/schemas/Entity'
target:
$ref: '#/components/schemas/Entity'
relations:
items:
$ref: '#/components/schemas/RelationEvidence'
type: array
title: Relations
description: Array of relation evidences
example: []
chunk_id:
type: string
title: Chunk Id
description: The chunk_id these relations are associated with
example:
type: object
required:
- source
- target
- relations
- chunk_id
title: TripletWithEvidence
description: Triple with multiple evidence items from different chunks
cortex__models__response__commons__ErrorResponse:
properties:
success:
type: boolean
title: Success
default: false
example: true
message:
type: string
title: Message
default: Error occurred
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
type: object
title: ErrorResponse
Entity:
properties:
name:
type: string
title: Name
description: Normalized entity name
example:
type:
type: string
title: Type
description: PERSON, ORGANIZATION, PROJECT, PRODUCT, ERROR_CODE, etc.
example:
namespace:
type: string
title: Namespace
description: Context category like 'employees', 'projects'
default: default
example:
entity_id:
type: string
title: Entity Id
description: Internal unique entity ID from graph database
example:
identifier:
anyOf:
- type: string
- type: 'null'
title: Identifier
description: Unique ID like email, employee_id, URL
type: object
required:
- name
- type
- entity_id
title: Entity
RelationEvidence:
properties:
canonical_predicate:
type: string
title: Canonical Predicate
description: Relationship phrase like 'works for', 'reports to'
example:
raw_predicate:
type: string
title: Raw Predicate
description: Original predicate from text
example:
context:
type: string
title: Context
description: >-
Rich contextual description of the relationship with surrounding
information, details about how/why/when, and any relevant
background. Should be comprehensive enough to understand the
relationship without referring back to source.
example:
confidence:
type: number
maximum: 1
minimum: 0
title: Confidence
description: Confidence score
default: 0.8
example: 1
temporal_details:
anyOf:
- type: string
- type: 'null'
title: Temporal Details
description: >-
Temporal timing information extracted from text (e.g., 'last week',
'in 2023', 'yesterday')
timestamp:
type: string
format: date-time
title: Timestamp
description: Timestamp when this relation was introduced
example:
relationship_id:
type: string
title: Relationship Id
description: Unique ID for this relationship from graph database
example:
chunk_id:
anyOf:
- type: string
- type: 'null'
title: Chunk Id
description: ID of the chunk this relation was extracted from
source_entity_id:
anyOf:
- type: string
- type: 'null'
title: Source Entity Id
description: The entity ID of source node
target_entity_id:
anyOf:
- type: string
- type: 'null'
title: Target Entity Id
description: The entity ID of target node
type: object
required:
- canonical_predicate
- raw_predicate
- context
- relationship_id
title: RelationEvidence
description: Single piece of evidence for a relationship between two entities
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````