[Canonical page](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# Metrics

Measures of one scored state compared with the baseline: finish dates, resource overload, conflict and cycle counts, and a single `cost` for ranking. [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>) returns one for the baseline and for each stage of each candidate; [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/js/api/project-suggest-assignments.md>) returns one for its proposal.

## Declaration

```ts
interface Metrics {
  finish: {
    project: Shift | null;
    tasks: { id: Id; finish: Shift | null }[];
  };
  overload: {
    total: Amount;
    resources: ResourceOverload[];
    focus: { task: Id; resources: ResourceOverload[] | null }[];
  };
  conflicts: Amount;
  cycles: Amount;
  cost: number;
}
```

## Fields

| Field | Type | Description |
|---|---|---|
| `finish.project` | [`Shift`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#shift>) `\| null` | Project finish: the latest end over scheduled tasks. `null` when the state has no tasks. |
| `finish.tasks` | `{ id, finish }[]` | One entry per focus task, in focus order. `finish` is the task's end as a [`Shift`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#shift>), or `null` when the task doesn't exist in this state. Empty without `focus`. |
| `overload.total` | [`Amount`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#amount>) | Overload summed over all resources. |
| `overload.resources` | [`ResourceOverload`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#resourceoverload>)`[]` | Overload per resource, for every resource that's non-zero in this state or in the baseline. Resources overloaded in this state come first, then those overloaded only in the baseline. |
| `overload.focus` | `{ task, resources }[]` | One entry per focus task: overload per resource over the time buckets the task spans, listed and ordered like `overload.resources`. `resources` is `null` when the task doesn't exist in this state. A milestone spans no bucket. Empty without `focus`. |
| `conflicts` | [`Amount`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#amount>) | Number of scheduling conflicts. |
| `cycles` | [`Amount`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#amount>) | Number of dependency cycles. |
| `cost` | `number` | Ranking score, lower is better: `max(0, finish.project.delta) + overload.total.value + 1000 × (conflicts.value + cycles.value)`. |

Overload is the sum over time buckets of `max(0, load − capacity)` for a resource. Its unit is capacity × buckets: on a day basis, `2` means two resource-days over capacity. For how the bucket basis is chosen and how to read these numbers, see [Evaluating alternatives](<https://docs.dhtmlx.com/planning-engine/js/resources-and-assignment/evaluating-alternatives.md#metrics-and-cost>).

Focus tasks come from the `focus` option of [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>).

## Shift

A finish date and its distance from the baseline finish.

| Field | Type | Description |
|---|---|---|
| `date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) | The finish date. A string, or a local `Date` when the project was created with `dates: "date"`. |
| `delta` | `number` | Working time from the baseline finish to `date`, in `config.duration_unit`. Positive when later. A task's delta is measured on the task's calendar, the project's on the global calendar. `0` in the baseline's own metrics. |

## Amount

A count or quantity and its change from the baseline.

| Field | Type | Description |
|---|---|---|
| `value` | `number` | The value in this state. |
| `delta` | `number` | `value` minus the baseline's value. `0` in the baseline's own metrics. |

## ResourceOverload

| Field | Type | Description |
|---|---|---|
| `resource` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) | Resource id. |
| `overload` | [`Amount`](<https://docs.dhtmlx.com/planning-engine/js/api/types/metrics.md#amount>) | The resource's overload and its change from the baseline. |

## LeveledMetrics

Metrics of a leveled state: every `Metrics` field plus a summary of the leveling run. Returned as `leveled` when leveling is requested.

```ts
interface LeveledMetrics extends Metrics {
  converged: boolean;
  rounds: number;
  windows: number;
}
```

| Field | Type | Description |
|---|---|---|
| `converged` | `boolean` | Whether the leveling run converged. |
| `rounds` | `number` | Number of leveling rounds run. |
| `windows` | `number` | Number of overallocation windows left after leveling, for any reason. |

:::note
Leveled metrics have the same fields as `Metrics` plus `converged`, `rounds` and `windows`.
:::

## Used by

- [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>): `baseline`, and each candidate's `scheduled` and `leveled`
- [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/js/api/project-suggest-assignments.md>): `proposed.scheduled` and `proposed.leveled`

## Example

A candidate that finishes one day later and removes two resource-days of overload from resource `"dev1"`:

```js
const metrics = {
  finish: {
    project: { date: "2026-03-20 17:00", delta: 1 },
    tasks: [{ id: "build", finish: { date: "2026-03-18 17:00", delta: 1 } }],
  },
  overload: {
    total: { value: 0, delta: -2 },
    resources: [{ resource: "dev1", overload: { value: 0, delta: -2 } }],
    focus: [{ task: "build", resources: [{ resource: "dev1", overload: { value: 0, delta: -2 } }] }],
  },
  conflicts: { value: 0, delta: 0 },
  cycles: { value: 0, delta: 0 },
  cost: 1,
};
```

## Related

- [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>) - scoring candidates against the baseline
- [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/js/api/project-suggest-assignments.md>) - the proposal scored with these metrics
- [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/types/leveling-options.md>) - options of the leveled stage
- [Evaluating alternatives](<https://docs.dhtmlx.com/planning-engine/js/resources-and-assignment/evaluating-alternatives.md>) - reading metrics and the cost formula