Reports APIs | UFM Cable Validation Tool

Get Validation Report

Description – Gets the recent cable validation report
Request URL – GET /cablevalidation/report/validation
Response Content Type – application/json
Status Codes
- 200 – OK
- 404 – NOT FOUND
Response Example

JSON

{
  "report": "ValidationReport",
  "stats": {
    "in_progress": 14,
    "no_issues": 8,
    "not_started": 5
  },
  "issues": [
    {
      "timestamp": 1722290755.0392804,
      "node_desc": "dell001.cm.cluster",
      "rack": "D01",
      "unit": 2,
      "issues": [
        ["Unreachable-device"]
      ]
    }
  ],
  "metadata": {
    "file_name": "v22_testing_extracable.xlsx",
    "file_hash": "d2a8ce40b613a17245acb3310fa0b810238dc61613e8f683b95139d19567aa5a",
    "load_time": 1722290305.0386324
  }
}

Get Validation Status

Description – Gets the current validation status and timing information.
Request URL – GET /cablevalidation/validation/status
Response Content Type – application/json
Status Codes
- 200 – OK
- 500 – INTERNAL SERVER ERROR

The started_at, started_by, duration_seconds, and last_cycle_seconds_ago fields can be null when validation has not started or when the corresponding information is unavailable.

Response Data Example

JSON

{
  "status": "started",
  "started_at": 1767225600,
  "started_by": "admin",
  "duration_seconds": 3600,
  "last_cycle_seconds_ago": 12
}

Get Topology Metadata

Description – Gets topology metadata. When topology statistics are available, the response includes switch, host, and link counts.
Request URL – GET /cablevalidation/topology/metadata
Response Content Type – application/json
Status Codes
- 200 – OK
- 400 – BAD REQUEST
Response Data Example

JSON

{
  "file_name": "proton-ptp.xlsx",
  "file_path": "/cable_bringup_root/data/uploads/topology/ptp/proton-ptp.xlsx",
  "dc_layout_file_path": null,
  "file_hash": "c13187caece919c9aa88d2c1e26404fe5e3d0cd56ea801c4c46a7236e42549fb",
  "file_id": "94a8c27f",
  "load_time": 1732376613.3298793,
  "switches_count": 32,
  "hosts_count": 96,
  "links_count": 128
}

Get Summary Report

Description – Gets the issue summary for a cluster. The response includes counts originating from stale agent reports when available.
Request URL – GET /cablevalidation/report/summary
Request Params
- cluster – Name of the cluster. If set, the response returns the device health for that specific cluster.
  - Type: string
  - Optional: true
  - Default: default
Response Content Type – application/json
Status Codes
- 200 – OK
- 400 – BAD REQUEST
- 404 – NOT FOUND
Response Example

JSON

[
  {
    "syndrome": "No Transceiver",
    "number_of_occurrences": 2,
    "switches_affected": 2,
    "number_of_occurrences_from_stale": 1,
    "switches_affected_from_stale": 1
  },
  {
    "syndrome": "Link Down, No signal",
    "number_of_occurrences": 3,
    "switches_affected": 2,
    "number_of_occurrences_from_stale": 0,
    "switches_affected_from_stale": 0
  }
]

Get Circuit Report

Description – Gets circuits information.
Request URL – GET /cablevalidation/report/circuits
Request Params
- cluster – Name of the cluster. If set, the response returns circuits for that specific cluster.
  - Type: string
  - Optional: true
  - Default: default
- node – Node name. If set, the response returns circuits for that node.
  - Type: string
  - Optional: true
- port – Port name. If set, the response returns circuits for that port.
  - Type: string
  - Optional: true
- page – Page type. Supported values: circuit, flap, and flap_hist.
  - Type: string
  - Optional: true
- healthy – If true, only healthy circuits are returned.
  - Type: bool
  - Optional: true
- circuit_id – Circuit identifier. If set, the response returns that circuit.
  - Type: string
  - Optional: true
- report – Syndrome name. If set, the response returns circuits with that syndrome.
  - Type: string
  - Optional: true
Response Content Type – application/json
Status Codes
- 200 – OK
- 400 – BAD REQUEST
- 404 – NOT FOUND
Response Example

JSON

[
  {
    "circuit_id": "c83df4d68b40",
    "a_endpoint": {
      "node_type": "Switch",
      "data_hall": "DH0",
      "su_number": "SU01",
      "node": "sw-hdr-proton01",
      "port": "P4",
      "rack": null,
      "unit": null,
      "actual_node": null,
      "actual_port": null,
      "port_status": "up",
      "plugged": true,
      "advanced_stats": {},
      "remediation_action": "Check LLDP is enabled on peer; Verify the peer is fully provisioned and reachable",
      "report": "Unknown-neighbor"
    },
    "z_endpoint": {},
    "healthy": false,
    "status": "Fail"
  }
]

Get Circuit Statistics

Description – Gets a summary of circuit health and agent-related circuit conditions.
Request URL – GET /cablevalidation/report/circuits/stats
Response Content Type – application/json
Status Codes
- 200 – OK
- 400 – BAD REQUEST
Response Fields
- total_circuits – Total number of circuits.
- healthy_circuits – Circuits without a detected issue.
- unhealthy_circuits – Active circuits with detected issues.
- not_active_circuits – Circuits that are not active.
- unreachable_circuits – Circuits affected by unreachable endpoints.
- stale_agent_circuits – Circuits affected by stale agent reports.
- not_tracked_circuits – Circuits that are not currently tracked.
- one_side_stale_circuits – Circuits with a stale report on one endpoint.
- both_sides_stale_circuits – Circuits with stale reports on both endpoints.
- no_agent_circuits – Circuits with at least one endpoint that does not have an agent.
Response Example

JSON

{
  "total_circuits": 250,
  "healthy_circuits": 210,
  "unhealthy_circuits": 25,
  "not_active_circuits": 15,
  "unreachable_circuits": 8,
  "stale_agent_circuits": 6,
  "not_tracked_circuits": 4,
  "one_side_stale_circuits": 3,
  "both_sides_stale_circuits": 2,
  "no_agent_circuits": 5
}

Get Device Health Report

Description – Gets the device health summary report.
Request URL – GET /cablevalidation/report/health
Request Params
- cluster – Name of the cluster. If set, the response returns device health for that specific cluster.
  - Type: string
  - Optional: true
  - Default: default
- context – dc, dh, su, rack, or node.
- items – Report scope, typically a list of data halls, scalable units/data halls, racks, or nodes depending on the selected context. Do not include this parameter when context is dc.
Response Content Type – application/json
Status Codes
- 200 – OK
- 400 – BAD REQUEST
Response Example

JSON

[
  {
    "health_summary": {
      "Power Supply": {
        "failed": 1,
        "active": 1
      },
      "Power Supply Fans": {
        "failed": 1,
        "active": 1
      },
      "Fans": {
        "failed": 0,
        "active": 12
      },
      "Ports": {
        "failed": 0,
        "active": 2
      }
    },
    "data_hall": null,
    "su_number": null,
    "rack": "PXX"
  }
]

Last updated: August 27, 2026