Skip to main content
GET
/
api
/
v1
/
graph
/
{entity_id}
Get Entity Graph
curl --request GET \
  --url https://api.example.com/api/v1/graph/{entity_id}
{
  "nodes": [
    {
      "id": "<string>",
      "label": "<string>",
      "type": "<string>",
      "document_id": "<string>",
      "properties": {},
      "sources": [
        {}
      ],
      "is_pep": true,
      "exposure_tier": "<string>"
    }
  ],
  "edges": [
    {
      "id": "<string>",
      "source": "<string>",
      "target": "<string>",
      "type": "<string>",
      "properties": {},
      "confidence": 123,
      "sources": [
        {}
      ],
      "exposure_tier": "<string>"
    }
  ],
  "center_id": "<string>"
}
Retrieve a subgraph centered on a specific entity, including connected nodes and relationships up to a specified depth.

​
Authentication

This endpoint requires authentication via:
  • Bearer token: Include Authorization: Bearer <token> header
  • Session cookie: Automatically sent by browser after login
Entity lookup must be enabled via the ENTITY_LOOKUP_ENABLED configuration.

​
Path Parameters

​
entity_id
string
required
Neo4j element ID of the center entity (e.g., 4:abc123:1)

​
Query Parameters

​
depth
integer
default:"2"
Graph traversal depth (minimum: 1, maximum: 4)Performance note: Depth is automatically capped at 1 for “supernodes” (entities with >500 connections) to prevent graph explosion.
​
entity_types
string
Comma-separated list of entity types to include in the graph. When specified, only these types and their relationships are returned.Available types:
  • person
  • company
  • contract
  • sanction
  • election
  • amendment
  • finance
  • embargo
  • health
  • education
  • convenio
  • laborstats
Example: entity_types=company,person

​
Response

​
nodes
array
Array of graph nodes
​
id
string
Unique Neo4j element ID
​
label
string
Display label extracted from node properties:
  • Company: razao_social or nome_fantasia
  • Finance: “Finance: R$ ” or transaction type
  • Embargo: description or state (UF)
  • Convenio: object or convenio_id
  • Other: name or id property
​
type
string
Entity type in lowercase
​
document_id
string
Primary identifier for the entity (CPF, CNPJ, contract_id, etc.)
​
properties
object
Slim property set optimized for graph rendering. Includes only essential fields:
  • name, razao_social, cnpj, cpf
  • value, date, type
  • uf, cargo, partido
​
sources
array
Data provenance information
​
is_pep
boolean
Politically Exposed Person flag
​
exposure_tier
string
Data sensitivity classification
​
edges
array
Array of relationships between nodes
​
id
string
Unique Neo4j relationship element ID
​
source
string
Element ID of source node
​
target
string
Element ID of target node
​
type
string
Relationship type (e.g., “HAS_PARTNER”, “WON_CONTRACT”, “SANCTIONED”)
​
properties
object
Relationship properties (e.g., role, start_date, percentage)
​
confidence
float
default:"1.0"
Relationship confidence score (0.0 to 1.0)
​
sources
array
Data provenance for the relationship
​
exposure_tier
string
Always “public_safe” for relationships
​
center_id
string
Element ID of the center entity (same as path parameter)

​
Example Request

curl -X GET "https://api.br-acc.com/api/v1/graph/4:abc123:1?depth=2&entity_types=company,person" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "nodes": [
    {
      "id": "4:abc123:1",
      "label": "Acme Construções LTDA",
      "type": "company",
      "document_id": "12345678000100",
      "properties": {
        "razao_social": "Acme Construções LTDA",
        "cnpj": "12.345.678/0001-00",
        "uf": "SP"
      },
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "is_pep": false,
      "exposure_tier": "public_safe"
    },
    {
      "id": "4:def456:2",
      "label": "João Silva",
      "type": "person",
      "document_id": "12345678900",
      "properties": {
        "name": "João Silva",
        "cpf": "123.456.789-00"
      },
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "is_pep": false,
      "exposure_tier": "public_safe"
    }
  ],
  "edges": [
    {
      "id": "5:rel123:1",
      "source": "4:def456:2",
      "target": "4:abc123:1",
      "type": "HAS_PARTNER",
      "properties": {
        "role": "Sócio Administrador",
        "start_date": "2020-01-15"
      },
      "confidence": 1.0,
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "exposure_tier": "public_safe"
    }
  ],
  "center_id": "4:abc123:1"
}

​
Performance Optimizations

​
Supernode Detection

From graph.py:108-120: Before graph expansion, the endpoint checks node degree:
  • If degree > 500, entity is classified as a “supernode”
  • Depth is automatically capped at 1 to prevent performance issues
  • Prevents graph explosion for highly connected entities

​
Property Slimming

From graph.py:69-71: Only essential properties are included in graph responses:
  • Reduces payload size for large graphs
  • Improves rendering performance in UI
  • Use the /entity/{entity_id} endpoint for full property details

​
Label Filtering

From graph.py:74-94: Internal system labels are automatically excluded:
  • -User - Application users
  • -Investigation - Investigation metadata
  • -Annotation - User annotations
  • -Tag - Custom tags
This ensures only domain entities appear in the graph.

​
Privacy Controls

When the HIDE_PERSON_ENTITIES environment variable is enabled:
  • Person nodes are filtered from graph results
  • Exception: Center entity can be a person if directly requested
  • Edges connecting to removed nodes are also excluded
  • This protects individual privacy in public deployments

​
Error Responses

​
401 Unauthorized
Missing or invalid authentication token
​
403 Forbidden
Person entity access denied (when center entity is a person and HIDE_PERSON_ENTITIES is enabled)
​
404 Not Found
Entity not found or has no connections
​
504 Gateway Timeout
Graph query exceeded 5-second timeout (typically for very large subgraphs)

​
Implementation Details

From graph.py:97-222:
  • Uses APOC subgraphAll for efficient graph expansion
  • Applies label filtering to exclude internal system nodes
  • Deduplicates nodes and edges in response
  • Enforces person access policies on center entity
  • Extracts document IDs from multiple property fields
  • Sanitizes properties before public exposure
  • Includes 5-second query timeout for safety

​
Use Cases

  1. Risk Analysis: Visualize connections between companies, contracts, and sanctions
  2. Ownership Structures: Map company partnerships and shareholding relationships
  3. Public Contract Networks: Trace government spending through contractors and amendments
  4. PEP Screening: Identify politically exposed persons in business networks
  5. Investigation Support: Explore entity relationships for due diligence

Build docs developers (and LLMs) love

Get started for freeTalk to us