> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-cloud/studio/tasks/reference/calculate-time-diff/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# calculateTimeDiff

> Use the calculateTimeDiff task to calculate the difference between two timestamps and return the result as a duration.

The `calculateTimeDiff` task calculates the difference between two timestamps and returns the result as a duration.

## Potential use case

Use this task to determine the remaining time (or elapsed time) between a recorded timestamp and today's date.

## Properties

### Input variables

| Incoming     | Type   | Description                                                                                                                                                                                                                                 | Example                                                                                         |
| :----------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------- |
| `firstTime`  | Object | Required. The base time from which `secondTime` is subtracted. Must contain `time` (string representation of the time) and `formatString` (the [moment.js format](https://momentjs.com/docs/#/displaying/format/) the time must adhere to). | `{ "formatString": "YYYY-MM-DDTHH:mm:ss.SSSSSSZZ", "time": "2023-06-21T15:02:07.254000-1100" }` |
| `secondTime` | Object | Required. The time subtracted from `firstTime`. Must contain the same `time` and `formatString` keys.                                                                                                                                       | `{ "formatString": "YYYY-MM-DDTHH:mm:ss.SSSSSSZZ", "time": "2023-04-28T01:21:14.052000-1100" }` |

### Output variables

| Outgoing   | Type   | Description                                                                                                                                           |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeDiff` | Object | The difference between the two timestamps expressed as a duration in multiple units (milliseconds, seconds, minutes, hours, days, months, and years). |

## Example 1

In this example:

* The `firstTime` property comes from the output of `addDuration`, another task in the workflow. The reference variable is `newtime`.
* The `secondTime` property comes from the `getTime` task. The reference variable is `time`.
* Because `secondTime` is less than `firstTime`, the outgoing `timeDiff` is a positive reference — for example, the number of days until a future date.

![](/_fern-img/a4b7683bab35d0bb572c4198f9843cf69fcadfa153c68f682fa8d9358293dd57.webp)

## Example 2

In this example:

* The `firstTime` property comes from the `getTime` task. The reference variable is `time`.
* The `secondTime` property comes from `addDuration`. The reference variable is `newTime`.
* Because `secondTime` is greater than `firstTime`, the outgoing `timeDiff` is a negative reference — for example, the elapsed time since the `firstTime` deadline was passed.

![](/_fern-img/6f017d4ae527a3a71fb8fed15eb1343712cc7878e127ef6ee7e9362a6c21c788.webp)

> Use the calculateTimeDiff task to calculate the difference between two timestamps and return the result as a duration.