> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Datetime Tool

> Inject the current date and time into model context. The datetime Server Tool gives models accurate time awareness without system prompt hacks.

The `datetime` Server Tool provides models with the current date and time. Instead of hardcoding dates in system prompts or relying on models' training cutoffs, use this tool to give models accurate, real-time temporal awareness.

## Quick Start

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [
    {"role": "user", "content": "What day of the week is today, and how many days until the end of the year?"}
  ],
  "tools": [
    {"type": "arouter", "arouter": {"id": "datetime"}}
  ]
}
```

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://api.arouter.ai/v1",
      apiKey: "lr_live_xxxx",
    });

    const response = await client.chat.completions.create({
      model: "openai/gpt-5.4",
      messages: [
        {
          role: "user",
          content: "What day of the week is today, and how many days until the end of the year?"
        }
      ],
      tools: [
        { type: "arouter", arouter: { id: "datetime" } } as any,
      ],
    });

    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.arouter.ai/v1",
        api_key="lr_live_xxxx",
    )

    response = client.chat.completions.create(
        model="openai/gpt-5.4",
        messages=[
            {
                "role": "user",
                "content": "What day of the week is today, and how many days until the end of the year?",
            }
        ],
        tools=[
            {"type": "arouter", "arouter": {"id": "datetime"}}
        ],
    )

    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/chat/completions \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "openai/gpt-5.4",
        "messages": [
          {
            "role": "user",
            "content": "What day of the week is today, and how many days until the end of the year?"
          }
        ],
        "tools": [
          {"type": "arouter", "arouter": {"id": "datetime"}}
        ]
      }'
    ```
  </Tab>
</Tabs>

***

## Configuration

```json theme={null}
{
  "tools": [
    {
      "type": "arouter",
      "arouter": {
        "id": "datetime",
        "timezone": "America/New_York"
      }
    }
  ]
}
```

| Parameter  | Type     | Default | Description                                                                                |
| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `id`       | `string` | —       | Must be `"datetime"`                                                                       |
| `timezone` | `string` | `"UTC"` | IANA timezone identifier (e.g. `"America/New_York"`, `"Asia/Shanghai"`, `"Europe/London"`) |

***

## Tool Response Format

When the model invokes `datetime`, ARouter returns the following structure as the tool result:

```json theme={null}
{
  "datetime": "2026-04-03T14:32:00Z",
  "date": "2026-04-03",
  "time": "14:32:00",
  "timezone": "UTC",
  "day_of_week": "Friday",
  "unix_timestamp": 1775319120
}
```

***

## Use Cases

**Scheduling and planning:**

```python theme={null}
response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[{
        "role": "user",
        "content": "Create a 2-week project plan starting from today for building a REST API."
    }],
    tools=[
        {"type": "arouter", "arouter": {"id": "datetime", "timezone": "Asia/Shanghai"}}
    ],
)
```

**Time-aware responses:**

```python theme={null}
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{
        "role": "user",
        "content": "Is it a good time to go for a morning run? I'm in Tokyo."
    }],
    tools=[
        {"type": "arouter", "arouter": {"id": "datetime", "timezone": "Asia/Tokyo"}}
    ],
)
```

***

## Pricing

The `datetime` tool is **free** — no additional charge beyond normal LLM token costs for the injected tool result.

***

## Next Steps

* [Web Search Tool](/en/guides/features/server-tools/web-search) — Real-time web search with citations
* [Server Tools Overview](/en/guides/features/server-tools/overview) — All available server tools