Date Math / Tools / time_buckets

Time buckets for charts and time series

Split a time range into minute, hour, day, week, month, quarter or year buckets with exact start and end times in a time zone. DST-aware (23- and 25-hour days, repeated and skipped hours), ISO or Sunday/Saturday weeks, fiscal quarters, partial first and last buckets flagged or clipped. Up to 1,000 buckets (500 for weeks and longer). Use for chart axes, time-series grouping and filling empty periods in dashboards.

MCP tool time_bucketsHTTP POST /v1/time_buckets25 free calls a day, then $0.001

Try it

Runs the real tool over MCP. Edit the arguments and run. Uses your daily free calls.

time_buckets

result

{
  "timezone": "America/New_York",
  "bucket": "day",
  "size": 1,
  "from": "2026-10-31T00:00:00-04:00",
  "to": "2026-11-03T00:00:00-05:00",
  "count": 3,
  "buckets": [
    {
      "label": "2026-10-31",
      "start": "2026-10-31T00:00:00-04:00",
      "end": "2026-11-01T00:00:00-04:00",
      "start_utc": "2026-10-31T04:00:00Z",
      "end_utc": "2026-11-01T04:00:00Z",
      "hours": 24
    }
  ]
}

The result shown before you run is a saved example response.

Use it from your agent

Add the MCP server once and your agent can call time_buckets and the other 22 tools.

Claude Code

One command in your terminal.

claude mcp add --transport http date-math https://date-math.datemath.workers.dev/mcp

Any MCP client

Claude Desktop, Cursor, VS Code, Windsurf.

{
  "mcpServers": {
    "date-math": {
      "url": "https://date-math.datemath.workers.dev/mcp"
    }
  }
}

HTTP + x402

POST JSON; pay the 402 with any x402 client.

curl -X POST https://date-math.datemath.workers.dev/v1/time_buckets \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-31","to":"2026-11-03","bucket":"day","timezone":"America/New_York"}'

Full schema: OpenAPI · llms.txt

Questions

Common questions, answered with real results from the tool.

Why does one day in my chart have 25 hours?

Days are local calendar days, so the day clocks go back has 25 hours and the day they go forward has 23. In New York, 2026-11-01 is a 25-hour day. Each bucket reports its real length in hours so rates and averages stay correct.

Can I group by fiscal quarter?

Yes. Use bucket quarter with fiscal_year_start. With a July fiscal year, January to March 2026 is labelled FY2026-Q3.

What happens to a partial first or last week?

By default buckets are whole calendar units, and any that extend past the range are flagged partial: true. Pass clip: true to cut the first and last buckets to the exact range instead.