---
title: "Get block dates"
method: GET
path: "/when"
tags: ["Chain Data"]
---

# Get block dates

`GET /when`

Find block(s) based on date, blockNum, timestamp, or 'special'. Corresponds to the <a href="/chifra/chaindata/#chifra-when">chifra when</a> command line.

## Query parameters

- `blocks` string[]
- `list` boolean
- `timestamps` boolean
- `count` boolean
- `repair` boolean
- `check` boolean
- `update` boolean
- `deep` number
- `chain` string
- `noHeader` boolean
- `cache` boolean
- `decache` boolean
- `fmt` string

## Response `200`

returns the requested data

- object
  - `data` union[] — Produces <a href="/data-model/other/#count">Count</a>, <a href="/data-model/other/#message">Message</a>, <a href="/data-model/chaindata/#namedblock">NamedBlock</a> or <a href="/data-model/chaindata/#timestamp">Timestamp</a> data. Corresponds to the <a href="/chifra/chaindata/#chifra-when">chifra when</a> command line.
    - union
      - Count — the number of items in the given database
        - `count` number — the number of items in the given database
      - Message — used for various responses when no real data is generated
        - `msg` string, string — the message
        - `num` number — a number if needed
      - NamedBlock — a block that has been given a particular name such as `first` or `latest`
        - `blockNumber` number — the number of the block
        - `timestamp` number — the Unix timestamp of the block
        - `date` string, datetime — the timestamp as a date (calculated)
        - `name` string, string — an optional name for the block
        - `description` string, string — an optional description of the block
      - Timestamp — the timestamp, date and difference in timestamp of previous block produced by chifra when
        - `blockNumber` number — the number of the block
        - `timestamp` number — the Unix timestamp of the block
        - `date` string, datetime — the timestamp as a date (calculated)
        - `diff` number — the number of seconds since the last block

## Other responses

- `400` — bad input parameter

## Changes

- **2025-07-23** `63aba50a45cb` — 1 breaking
  - for the `query` request parameter `deep`, the type/format was changed from `boolean`/`` to `number`/`uint64`
- **2024-12-17** `2428f6f19a07` — 1 breaking, 1 info
  - added `#/components/schemas/count` to the `data/items/` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/timestampCount` from the `data/items/` response property `oneOf` list for the response status `200`
- **2024-05-03** `bd3425654b91` — 1 breaking
  - the `data/items/oneOf[#/components/schemas/message]/num` response's property type/format changed from `string`/`int` to `number`/`int64` for status `200`
- **2024-04-30** `b2da4e150982` — 1 breaking, 1 info
  - added `#/components/schemas/message` to the `data/items/` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/block` from the `data/items/` response property `oneOf` list for the response status `200`
- **2024-04-10** `92d116712599` — 2 breaking, 1 info
  - for the `query` request parameter `deep`, the type/format was changed from `number`/`uint64` to `boolean`/``
  - added `#/components/schemas/block, #/components/schemas/timestampCount` to the `data/items/` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/count, #/components/schemas/message` from the `data/items/` response property `oneOf` list for the response status `200`

[Change history](https://skmtc.dev/trueblocks/apis/trueblocks-api/changes/when/get.md)

---

[API](https://skmtc.dev/trueblocks/apis/trueblocks-api.md) · [All operations](https://skmtc.dev/trueblocks/apis/trueblocks-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trueblocks/trueblocks-api/revisions/2a176f1485a9/schema)