Datetime Tool

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

{
  "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"}}
  ]
}

TypeScript
Python
cURL

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);

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)

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"}}
    ]
  }'

Configuration

{
  "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:

{
  "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:

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:

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 — Real-time web search with citations
Server Tools Overview — All available server tools

Get Started

Core Concepts

Routing

Features

Guides

Privacy

Administration

Best Practices

Frameworks & Integrations

For Providers

Support

Quick Start

Configuration

Tool Response Format

Use Cases

Pricing

Next Steps

​Quick Start

​Configuration

​Tool Response Format

​Use Cases

​Pricing

​Next Steps

Quick Start

Configuration

Tool Response Format

Use Cases

Pricing

Next Steps