Look up employment relationships between entities using a directional source → target query. Use a business as source to find its employees, or a person as source to find their employers. Each direction answers a different question, and results are returned in a consistent source/target format.
Quick Example
{
"source_entity_type": "person",
"source_entity_ids": ["123"],
"relationship": "employs",
"target_entity_type": "business"
}Input Parameters
| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| source_entity_type | string | Yes | - | "person" or "business" | Type of the source entities being provided |
| source_entity_ids | array | Conditional | - | 1-200000 string IDs; each must be a valid non-negative integer | Source entity IDs. Mutually exclusive with csv_resource_uri |
| csv_resource_uri | string | Conditional | - | workflow:// URI | CSV with source entity IDs. Mutually exclusive with source_entity_ids |
| entity_id_column | string | No | "entity_id" | Column name | Column containing entity IDs (only with csv_resource_uri) |
| relationship | string | No | - | "employs" | Filter by relationship type. Currently only "employs" is supported |
| target_entity_type | string | No | - | "person" or "business" | Filter by type of target entities returned |
| limit | number | No | See below | 1-100000 | Maximum relations to return. Defaults to 10 when format is "none", 10000 when exporting |
| offset | number | No | 0 | >= 0 | Pagination offset |
| format | string | No | "none" | "none", "csv", "json", "jsonl" | Export format. When not "none", generates a presigned download URL valid for 1 hour |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier |
Request Schema:
interface EntityRelationsParams {
source_entity_type: "person" | "business";
source_entity_ids?: string[];
csv_resource_uri?: string;
entity_id_column?: string;
relationship?: "employs";
target_entity_type?: "person" | "business";
limit?: number;
offset?: number;
format?: "none" | "csv" | "json" | "jsonl";
workflow_id?: string;
}Output Format
{
relations: Array<{
source_entity_id: string;
target_entity_id: string;
target_entity_type: "person" | "business";
relationship: string;
}>,
total: number,
returned: number,
has_more: boolean,
next_offset?: number,
export?: {
url: string;
format: "csv" | "json" | "jsonl";
rows: number;
expires_at: string;
resource_uri: string;
},
tool_trace_id: string,
workflow_id: string
}Response Fields:
| Field | Type | Description |
|---|---|---|
| relations | array | Array of entity relationships |
| relations[].source_entity_id | string | The source entity ID |
| relations[].target_entity_id | string | The target (related) entity ID |
| relations[].target_entity_type | string | Type of the target entity |
| relations[].relationship | string | Relationship type |
| total | number | Total matching relations |
| returned | number | Number returned in this page |
| has_more | boolean | Whether more results exist |
| next_offset | number | Offset for next page |
| export | object | Export metadata (when format is csv/json/jsonl) |
| export.url | string | Presigned download URL (valid 1 hour) |
| export.format | string | Export format used |
| export.rows | number | Number of rows exported |
| export.expires_at | string | ISO timestamp when the URL expires |
| export.resource_uri | string | Workflow resource URI for the exported file |
| tool_trace_id | string | OpenTelemetry trace ID |
| workflow_id | string | Workflow session identifier |
Example Response:
{
"relations": [
{
"source_entity_id": "123",
"target_entity_id": "456",
"target_entity_type": "business",
"relationship": "employs"
}
],
"total": 1,
"returned": 1,
"has_more": false,
"tool_trace_id": "a1b2c3d4e5f6",
"workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}Error Handling
Common Errors:
- Both source_entity_ids and csv_resource_uri provided:
"source_entity_ids and csv_resource_uri are mutually exclusive. Provide one or the other." - Neither provided:
"Either source_entity_ids or csv_resource_uri must be provided." - Non-integer entity ID:
"Invalid entity_id \"<value>\": must be a valid non-negative integer" - V2 schema not active:
"entity_relations is only available with the V2 schema. Current schema does not support entity relations."
Usage Examples
Example 1: Find employers of a person
{
"source_entity_type": "person",
"source_entity_ids": ["123"],
"relationship": "employs",
"target_entity_type": "business"
}Example 2: Find employees of a business
{
"source_entity_type": "business",
"source_entity_ids": ["456"],
"relationship": "employs",
"target_entity_type": "person"
}Example 3: All relationships for an entity
{
"source_entity_type": "person",
"source_entity_ids": ["123"]
}Example 4: CSV resource input with pagination
{
"source_entity_type": "person",
"csv_resource_uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/people.csv",
"entity_id_column": "entity_id",
"limit": 500,
"offset": 0
}Example 5: Export all relations to CSV
{
"source_entity_type": "business",
"source_entity_ids": ["456"],
"relationship": "employs",
"target_entity_type": "person",
"format": "csv",
"limit": 50000
}