Skip to content
POST/api/v1/health/score

Calculate Schedule Health Score

Calculate comprehensive schedule health score (0-100) based on deterministic analysis.

This endpoint performs:

  • DAG construction and validation
  • Critical Path Method (CPM) calculation
  • Float analysis and erosion detection
  • Critical path density evaluation
  • Structural integrity assessment
  • Weighted composite of four deterministic component scores. The weights are this route's: criticality 0.40, float erosion 0.35, structural integrity 0.15, critical-path density 0.10. They are not taken from a standard. Letter grade is this route's: A at 90, B at 80, C at 70, D at 60, otherwise F. The pass line is 70. Criticality is the share of tasks on the critical path. Float erosion is the average total float of tasks with float above zero. Density is the average number of dependencies. Structural integrity starts at 100 and subtracts for duplicate ids, broken links, negative duration, and missing logic. The band edges and the deductions are on the API reference page.

Performance Target: Response time <5s for 1,000 tasks (Phase 1A)

Task Limits:

  • Synchronous processing: up to 1,000 tasks
  • Tier-based limits: Free (500), Professional (5,000), Enterprise (50,000+)

Source: no compliance document states this composite or these weights. GAO-16-89G practice 6 says the schedule should identify the critical path, the path of longest duration through the sequence of activities. That sentence is not this formula. DCMA-EA PAM 200.1 and the DECM sheets are cited on POST /api/v1/health/dcma-14-point and POST /api/v1/health/dcma-decm, not here. This path is not POST /api/v1/schedule/health or POST /api/v1/schedule/analyze. Those paths return 410 and are not aliases.

Health score

The OpenAPI description is the overview. This page is the arithmetic. The weights, the bands, and the deductions are this route's. No compliance document states them.

The route runs critical path method on the tasks, then scores four components. Tasks may be listed in any order. A predecessor loop has no critical path, so the request returns 400 CIRCULAR_DEPENDENCY with the task IDs in cycle; a task that depends on itself is scored as a structural defect instead.

score = 0.40 × criticality + 0.35 × float erosion + 0.10 × density + 0.15 × structural

The result is clamped to 0–100. Letter grade: A at 90, B at 80, C at 70, D at 60, otherwise F. Pass is 70. Warning is 49 or above and below 70.

GAO-16-89G practice 6 says the schedule should identify the critical path, the path of longest duration through the sequence of activities. That sentence is not this formula. PAM 200.1 and the DECM sheets are cited on the 14-point and DECM routes, not here.

Criticality (0.40)

Density is the number of tasks on the critical path divided by the task count.

Density Score
Below 15% 100
15% up to 30% 75 + (0.30 − density) / 0.15 × 25
30% up to 50% 35 + (0.50 − density) / 0.20 × 40
50% and above 35 × (1 − (density − 0.5) / 0.5), not below 0

A task with total float above 0 and at most 5 days is reported as near-critical. That list does not change the score.

Float erosion (0.35)

Average total float of tasks whose total float is above 0. If there is no such task, or the share of tasks with no positive float is above 70%, the score is 30.

Average float Score
10 days or more 100
5 days up to 10 65 + (average − 5) / 5 × 35
2 days up to 5 30 + (average − 2) / 3 × 35
Below 2 days 30 × average / 2, not below 0

This is not PAM 200.1 section 4.6. That section counts incomplete tasks with total float greater than 44 working days and flags a share above 5%.

Density (0.10)

Average number of dependencies per task.

Average dependencies Score
2 or fewer 100
Above 2, up to 3 80 + (3 − average) × 20
Above 3, up to 4 60 + (4 − average) × 20
Above 4 60 − (average − 4) × 15, not below 0

If isolated discrete tasks are more than 10% of the schedule, the score is multiplied by (1 − 0.5 × that share). PAM 200.1 section 4.1 is a missing-logic percentage. It is not this average.

Structural integrity (0.15)

Starts at 100. Deductions, then not below 0.

Condition Deduction
Any duplicate task id 30
Each self-dependency 15
Predecessor ids that are not tasks 15 per reference, at most 30
Each negative duration 10, at most 20
Zero-duration tasks above 10% of the schedule 10
More than one discrete task with no predecessor 5 per extra task, at most 15
More than one discrete task with no successor 5 per extra task, at most 20
Each isolated discrete task 10, at most 20

One discrete task with no predecessor and one with no successor are not deducted. That exception is this score's. Section 4.1 includes any incomplete task missing a predecessor or a successor and flags a share above 5%. Dangling starts and finishes are reported. They do not change this score.

Defect labels

Code What it counts Where the sentence is
MISSING_LOGIC Discrete tasks missing a predecessor or a successor, after the one-start and one-finish exception PAM 200.1 §4.1. This defect is not the 5% flag.
DANGLING_START, DANGLING_FINISH A predecessor that does not constrain the start, or a successor that does not constrain the finish DECM 06A204b. The score deduction above does not apply. The label is the metric id.
DUPLICATE_ID Duplicate task ids Not a cited standard.
HIGH_DURATION Duration above 44 days PAM 200.1 §4.8 names 44 working days and a 5% flag, and it also requires the baseline start to fall in the detail planning period. This defect is the duration test only.

The async route is the same score. It returns a job id.

Request example

json
json
{
  "tasks": [
    {
      "id": "T1",
      "duration_days": 5
    }
  ]
}

Request fields from OpenAPI contract

Required fields and the optional fields that change this call are listed here. The shared task model stays on the task schema guide.

This table is generated from the endpoint schema in openapi.json.

FieldTypeRequiredDescription
tasksarray<unknown>RequiredList of tasks in the schedule
tasks[].idstringRequiredUnique task identifier
include_detailsbooleanOptionalInclude detailed task-level diagnostics and actionable recommendations
use_ml_scoringbooleanOptionalUse ML ensemble model for score aggregation with SHAP explainability (Professional+ tiers only)

Response example

json
json
{
  "score": 92,
  "grade": "A"
}

Response fields from OpenAPI contract

This table is generated from the endpoint response schema in openapi.json.

FieldTypeRequiredDescription
statusstringRequiredTop-level result status — always present in every response.
metadataobjectRequiredAudit trail and processing context — always present, never null.
metadata.task_countintegerRequiredNumber of tasks in the submitted schedule
metadata.endpointstringRequiredEndpoint path e.g. /api/v1/health/score

Schema

json-schema
{
  "$ref": "#/components/schemas/BellatorResponse_HealthScoreData_"
}

Authentication

  • API key required

Reference details

Operation ID
health_score
Section
Health
Tags
Health
Playground link
/playground?endpoint=/api/v1/health/score&method=post

Was this page helpful?

Your feedback helps us improve docs, reference pages, and Playground flows.

Topic: Calculate Schedule Health Score · Page: /docs/api-reference/health_score

TermsPrivacyContact

Schedule analysis guidance. Not legal advice. You remain responsible for contract and agency compliance.