Topology: Trace

Base URL: $BUSINESS_API

Nodes and links feeding a node

Logs

GET /topology/trace/upstream

Walks against the flow direction from a start node to find what feeds it, returning each reached node with its depth in links and the links traversed; the start node itself is not listed. By default closed links and inactive nodes stop the trace. Responds 400 when node_id is missing and 404 when it is not a topology node; requires network read access.

Parameters

node_idstring · query · required

Required ID of the topology node to trace back from.

include_closedboolean · query · optional

Boolean (true or false, default false); when true the trace also passes through closed links and continues past inactive nodes.

Returns

200 Trace

Show attributes
start_node_idstring · optional
directionstring · optional

one of upstream, downstream

include_closedboolean · optional
nodesarray of object · optional
Show child attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · required
updated_atstring (date-time) · required
depthinteger · optional
linksarray of TopologyLink · optional
Show child attributes
idstring · required
tenant_idstring · required
link_codestring · required
from_node_idstring · required
to_node_idstring · required
link_typestring · required

one of gravity_main, pumping_main, distribution_pipe, control_valve

length_metersnumber · required
diameter_mminteger · required
roughness_coefficientinteger · required

Hazen-Williams C

statusstring · required

one of open, closed, throttled

asset_idstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/trace/upstream" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "start_node_id": "sta_2r9QwjrYCzhCIxhykbbmgFLiy1J",
  "direction": "upstream",
  "include_closed": true,
  "nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z",
      "depth": 1
    }
  ],
  "links": [
    {
      "id": "top_26ATL6Y7Pm2ppeMTl60jhySNHae",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "link_code": "LIN-2026-000142",
      "from_node_id": "fro_2b3GWtBsQPTMCF5SOjDUUp7QKHr",
      "to_node_id": "ton_2qKn74u1zmYRZmiRFqqbFqoplME",
      "link_type": "gravity_main",
      "length_meters": 1,
      "diameter_mm": 1,
      "roughness_coefficient": 1,
      "status": "open",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Nodes and links fed by a node

Logs

GET /topology/trace/downstream

Follows the flow direction from a start node and returns every node it reaches with its depth in links from the start, plus the links traversed; the start node itself is not listed. By default closed links and inactive nodes stop the trace. Responds 400 when node_id is missing and 404 when it is not a topology node; requires network read access.

Parameters

node_idstring · query · required

Required ID of the topology node to start the trace from.

include_closedboolean · query · optional

Boolean (true or false, default false); when true the trace also passes through closed links and continues past inactive nodes, showing what the network reaches once valves are opened.

Returns

200 Trace

Show attributes
start_node_idstring · optional
directionstring · optional

one of upstream, downstream

include_closedboolean · optional
nodesarray of object · optional
Show child attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · required
updated_atstring (date-time) · required
depthinteger · optional
linksarray of TopologyLink · optional
Show child attributes
idstring · required
tenant_idstring · required
link_codestring · required
from_node_idstring · required
to_node_idstring · required
link_typestring · required

one of gravity_main, pumping_main, distribution_pipe, control_valve

length_metersnumber · required
diameter_mminteger · required
roughness_coefficientinteger · required

Hazen-Williams C

statusstring · required

one of open, closed, throttled

asset_idstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/trace/downstream" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "start_node_id": "sta_2r9QwjrYCzhCIxhykbbmgFLiy1J",
  "direction": "upstream",
  "include_closed": true,
  "nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z",
      "depth": 1
    }
  ],
  "links": [
    {
      "id": "top_26ATL6Y7Pm2ppeMTl60jhySNHae",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "link_code": "LIN-2026-000142",
      "from_node_id": "fro_2b3GWtBsQPTMCF5SOjDUUp7QKHr",
      "to_node_id": "ton_2qKn74u1zmYRZmiRFqqbFqoplME",
      "link_type": "gravity_main",
      "length_meters": 1,
      "diameter_mm": 1,
      "roughness_coefficient": 1,
      "status": "open",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Trace valve isolation

Logs

GET /topology/trace/valve-isolation

Which valves take a link out of service and what loses supply

Compares network-wide supply before and after, so a node fed by another path is not reported isolated.

Parameters

link_idstring · query · required

Required ID of the topology link to take out of service; the response lists the valves to close (the link itself when it is a valve), the nodes that lose supply and those still fed by another path.

Returns

200 Isolation analysis

Show attributes
link_idstring · optional
closed_valvesarray of TopologyLink · optional
Show child attributes
idstring · required
tenant_idstring · required
link_codestring · required
from_node_idstring · required
to_node_idstring · required
link_typestring · required

one of gravity_main, pumping_main, distribution_pipe, control_valve

length_metersnumber · required
diameter_mminteger · required
roughness_coefficientinteger · required

Hazen-Williams C

statusstring · required

one of open, closed, throttled

asset_idstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
isolated_nodesarray of TopologyNode · optional
Show child attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · required
updated_atstring (date-time) · required
still_supplied_nodesarray of TopologyNode · optional
Show child attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · required
updated_atstring (date-time) · required
affected_customer_tapsinteger · optional
unisolableboolean · optional

A pipe has an upstream path to a source with no valve

already_closedboolean · optional

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/trace/valve-isolation" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "link_id": "lin_2QKtDAGrlWKVjKUX5USfBwe1zSi",
  "closed_valves": [
    {
      "id": "top_26ATL6Y7Pm2ppeMTl60jhySNHae",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "link_code": "LIN-2026-000142",
      "from_node_id": "fro_2b3GWtBsQPTMCF5SOjDUUp7QKHr",
      "to_node_id": "ton_2qKn74u1zmYRZmiRFqqbFqoplME",
      "link_type": "gravity_main",
      "length_meters": 1,
      "diameter_mm": 1,
      "roughness_coefficient": 1,
      "status": "open",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "isolated_nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "still_supplied_nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "affected_customer_taps": 1,
  "unisolable": true,
  "already_closed": true
}