> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Time & Date

> Time operations for timestamps, parsing, and calculations

## Overview

The time tool provides operations for getting current time, parsing timestamps, formatting dates, and calculating time differences.

## time

Get current time, convert timezones, or calculate time differences.

**Input Parameters**

<ParamField path="operation" type="string" required>
  The time operation to perform. Must be one of: `now`, `parse`, `format`, `diff`
</ParamField>

<ParamField path="timestamp" type="string">
  ISO 8601 timestamp for parse/format/diff operations
</ParamField>

<ParamField path="format" type="string">
  Output format string (for format operation)
</ParamField>

<ParamField path="timestamp2" type="string">
  Second timestamp for diff operation
</ParamField>

## Operations

### now

Get the current UTC time.

**Input**

No additional parameters required.

**Output**

<ResponseField name="iso" type="string">
  RFC3339 formatted timestamp (ISO 8601)
</ResponseField>

<ResponseField name="unix" type="integer">
  Unix timestamp in seconds since epoch
</ResponseField>

<ResponseField name="unix_millis" type="integer">
  Unix timestamp in milliseconds since epoch
</ResponseField>

**Example**

```json theme={null}
{
  "operation": "now"
}
```

**Response**

```json theme={null}
{
  "iso": "2024-01-15T14:30:00.123Z",
  "unix": 1705329000,
  "unix_millis": 1705329000123
}
```

***

### parse

Parse an ISO 8601 timestamp string into multiple formats.

**Input**

<ParamField path="timestamp" type="string" required>
  ISO 8601 timestamp string to parse
</ParamField>

**Output**

<ResponseField name="iso" type="string">
  RFC3339 formatted timestamp
</ResponseField>

<ResponseField name="unix" type="integer">
  Unix timestamp in seconds
</ResponseField>

<ResponseField name="unix_millis" type="integer">
  Unix timestamp in milliseconds
</ResponseField>

**Example**

```json theme={null}
{
  "operation": "parse",
  "timestamp": "2024-01-15T14:30:00Z"
}
```

**Response**

```json theme={null}
{
  "iso": "2024-01-15T14:30:00+00:00",
  "unix": 1705329000,
  "unix_millis": 1705329000000
}
```

**Error Conditions**

* `InvalidParameters`: Invalid timestamp format (must be ISO 8601)

***

### diff

Calculate the time difference between two timestamps.

**Input**

<ParamField path="timestamp" type="string" required>
  First ISO 8601 timestamp (earlier time)
</ParamField>

<ParamField path="timestamp2" type="string" required>
  Second ISO 8601 timestamp (later time)
</ParamField>

**Output**

<ResponseField name="seconds" type="integer">
  Difference in seconds (timestamp2 - timestamp)
</ResponseField>

<ResponseField name="minutes" type="integer">
  Difference in minutes
</ResponseField>

<ResponseField name="hours" type="integer">
  Difference in hours
</ResponseField>

<ResponseField name="days" type="integer">
  Difference in days
</ResponseField>

**Example**

```json theme={null}
{
  "operation": "diff",
  "timestamp": "2024-01-15T10:00:00Z",
  "timestamp2": "2024-01-15T14:30:00Z"
}
```

**Response**

```json theme={null}
{
  "seconds": 16200,
  "minutes": 270,
  "hours": 4,
  "days": 0
}
```

<Note>
  All durations are signed. If `timestamp2` is before `timestamp`, values will be negative.
</Note>

**Error Conditions**

* `InvalidParameters`: Invalid timestamp or timestamp2 format

## Examples

### Get Current Time

```json theme={null}
{
  "operation": "now"
}
```

### Parse Date String

```json theme={null}
{
  "operation": "parse",
  "timestamp": "2024-01-15T09:00:00-05:00"
}
```

**Response:**

```json theme={null}
{
  "iso": "2024-01-15T14:00:00+00:00",
  "unix": 1705327200,
  "unix_millis": 1705327200000
}
```

### Calculate Time Elapsed

```json theme={null}
{
  "operation": "diff",
  "timestamp": "2024-01-01T00:00:00Z",
  "timestamp2": "2024-01-15T14:30:00Z"
}
```

**Response:**

```json theme={null}
{
  "seconds": 1243800,
  "minutes": 20730,
  "hours": 345,
  "days": 14
}
```

### Negative Difference

```json theme={null}
{
  "operation": "diff",
  "timestamp": "2024-01-15T14:00:00Z",
  "timestamp2": "2024-01-15T10:00:00Z"
}
```

**Response:**

```json theme={null}
{
  "seconds": -14400,
  "minutes": -240,
  "hours": -4,
  "days": 0
}
```

## Use Cases

### Log Timestamping

Get current time for log entries:

```json theme={null}
{
  "operation": "now"
}
```

### Duration Tracking

Calculate how long a task took:

```json theme={null}
{
  "operation": "diff",
  "timestamp": "<start_time>",
  "timestamp2": "<end_time>"
}
```

### Deadline Checking

Calculate days until deadline:

```json theme={null}
{
  "operation": "diff",
  "timestamp": "<now>",
  "timestamp2": "<deadline>"
}
```

### Parse External Timestamps

Convert timestamps from APIs or logs:

```json theme={null}
{
  "operation": "parse",
  "timestamp": "<external_timestamp>"
}
```

## Technical Details

### Timezone Handling

All timestamps are normalized to UTC. Input timestamps with timezone offsets (e.g., `-05:00`) are converted to UTC for comparison and output.

### ISO 8601 Format

Accepted timestamp formats:

* `2024-01-15T14:30:00Z` (UTC)
* `2024-01-15T14:30:00+00:00` (UTC with offset)
* `2024-01-15T09:30:00-05:00` (with timezone offset)
* `2024-01-15T14:30:00.123Z` (with milliseconds)

### Duration Precision

* `seconds`: Exact duration in seconds
* `minutes`: Truncated to whole minutes
* `hours`: Truncated to whole hours
* `days`: Truncated to whole days

Example: 25.5 hours = 25 hours, 0 days

### Sanitization

No sanitization required - internal tool with no external data access.

### Approval

No approval required - safe internal operation.

## Error Handling

<ResponseField name="InvalidParameters">
  * Unknown operation
  * Missing required timestamp parameter
  * Invalid ISO 8601 timestamp format
</ResponseField>