> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/api/stacks-blockchain-api/blocks.md).

# Blocks

Read-only endpoints to obtain Stacks block details

## Get blocks

> Retrieves a list of recently mined blocks

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Blocks","description":"Read-only endpoints to obtain Stacks block details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v2/blocks/":{"get":{"operationId":"get_blocks","summary":"Get blocks","tags":["Blocks"],"description":"Retrieves a list of recently mined blocks","parameters":[{"schema":{"minimum":0,"default":20,"maximum":30,"title":"Limit","type":"integer"},"in":"query","name":"limit","required":false,"description":"Results per page"},{"schema":{"default":0,"maximum":300,"minimum":-300,"title":"Offset","type":"integer"},"in":"query","name":"offset","required":false,"description":"Result offset"},{"schema":{"pattern":"^0x[a-fA-F0-9]{64}$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for block pagination"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["limit","offset","total","next_cursor","prev_cursor","cursor","results"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"next_cursor":{"anyOf":[{"description":"Next page cursor","type":"string"},{"type":"null"}]},"prev_cursor":{"anyOf":[{"description":"Previous page cursor","type":"string"},{"type":"null"}]},"cursor":{"anyOf":[{"description":"Current page cursor","type":"string"},{"type":"null"}]},"results":{"type":"array","items":{"type":"object","required":["canonical","height","hash","block_time","block_time_iso","tenure_height","index_block_hash","parent_block_hash","parent_index_block_hash","burn_block_time","burn_block_time_iso","burn_block_hash","burn_block_height","miner_txid","tx_count","execution_cost_read_count","execution_cost_read_length","execution_cost_runtime","execution_cost_write_count","execution_cost_write_length"],"properties":{"canonical":{"description":"Set to `true` if block corresponds to the canonical chain tip","type":"boolean"},"height":{"description":"Height of the block","type":"integer"},"hash":{"description":"Hash representing the block","type":"string"},"block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"tenure_height":{"description":"The tenure height (AKA coinbase height) of this block","type":"integer"},"index_block_hash":{"description":"The only hash that can uniquely identify an anchored block or an unconfirmed state trie","type":"string"},"parent_block_hash":{"description":"Hash of the parent block","type":"string"},"parent_index_block_hash":{"description":"Index block hash of the parent block","type":"string"},"burn_block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"burn_block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"burn_block_hash":{"description":"Hash of the anchor chain block","type":"string"},"burn_block_height":{"description":"Height of the anchor chain block","type":"integer"},"miner_txid":{"description":"Anchor chain transaction ID","type":"string"},"tx_count":{"description":"Number of transactions included in the block","type":"integer"},"execution_cost_read_count":{"description":"Execution cost read count.","type":"integer"},"execution_cost_read_length":{"description":"Execution cost read length.","type":"integer"},"execution_cost_runtime":{"description":"Execution cost runtime.","type":"integer"},"execution_cost_write_count":{"description":"Execution cost write count.","type":"integer"},"execution_cost_write_length":{"description":"Execution cost write length.","type":"integer"}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}
```

## Get average block times

> Retrieves average block times (in seconds)

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Blocks","description":"Read-only endpoints to obtain Stacks block details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v2/blocks/average-times":{"get":{"operationId":"get_average_block_times","summary":"Get average block times","tags":["Blocks"],"description":"Retrieves average block times (in seconds)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["last_1h","last_24h","last_7d","last_30d"],"properties":{"last_1h":{"description":"Average block times over the last hour (in seconds)","type":"number"},"last_24h":{"description":"Average block times over the last 24 hours (in seconds)","type":"number"},"last_7d":{"description":"Average block times over the last 7 days (in seconds)","type":"number"},"last_30d":{"description":"Average block times over the last 30 days (in seconds)","type":"number"}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}
```

## Get block by block time

> Retrieves the most recent block mined at or before a given Unix timestamp (in seconds)

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Blocks","description":"Read-only endpoints to obtain Stacks block details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v2/blocks/by-block-time/{timestamp}":{"get":{"operationId":"get_block_by_block_time","summary":"Get block by block time","tags":["Blocks"],"description":"Retrieves the most recent block mined at or before a given Unix timestamp (in seconds)","parameters":[{"schema":{"minimum":0,"title":"Block timestamp","type":"integer"},"in":"path","name":"timestamp","required":true,"description":"Unix timestamp (in seconds)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["canonical","height","hash","block_time","block_time_iso","tenure_height","index_block_hash","parent_block_hash","parent_index_block_hash","burn_block_time","burn_block_time_iso","burn_block_hash","burn_block_height","miner_txid","tx_count","execution_cost_read_count","execution_cost_read_length","execution_cost_runtime","execution_cost_write_count","execution_cost_write_length"],"properties":{"canonical":{"description":"Set to `true` if block corresponds to the canonical chain tip","type":"boolean"},"height":{"description":"Height of the block","type":"integer"},"hash":{"description":"Hash representing the block","type":"string"},"block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"tenure_height":{"description":"The tenure height (AKA coinbase height) of this block","type":"integer"},"index_block_hash":{"description":"The only hash that can uniquely identify an anchored block or an unconfirmed state trie","type":"string"},"parent_block_hash":{"description":"Hash of the parent block","type":"string"},"parent_index_block_hash":{"description":"Index block hash of the parent block","type":"string"},"burn_block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"burn_block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"burn_block_hash":{"description":"Hash of the anchor chain block","type":"string"},"burn_block_height":{"description":"Height of the anchor chain block","type":"integer"},"miner_txid":{"description":"Anchor chain transaction ID","type":"string"},"tx_count":{"description":"Number of transactions included in the block","type":"integer"},"execution_cost_read_count":{"description":"Execution cost read count.","type":"integer"},"execution_cost_read_length":{"description":"Execution cost read length.","type":"integer"},"execution_cost_runtime":{"description":"Execution cost runtime.","type":"integer"},"execution_cost_write_count":{"description":"Execution cost write count.","type":"integer"},"execution_cost_write_length":{"description":"Execution cost write length.","type":"integer"}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}
```

## Get block

> Retrieves a single block

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Blocks","description":"Read-only endpoints to obtain Stacks block details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v2/blocks/{height_or_hash}":{"get":{"operationId":"get_block","summary":"Get block","tags":["Blocks"],"description":"Retrieves a single block","parameters":[{"schema":{"anyOf":[{"type":"string","enum":["latest"]},{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},{"title":"Block height","description":"Block height","type":"integer"}]},"in":"path","name":"height_or_hash","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["canonical","height","hash","block_time","block_time_iso","tenure_height","index_block_hash","parent_block_hash","parent_index_block_hash","burn_block_time","burn_block_time_iso","burn_block_hash","burn_block_height","miner_txid","tx_count","execution_cost_read_count","execution_cost_read_length","execution_cost_runtime","execution_cost_write_count","execution_cost_write_length"],"properties":{"canonical":{"description":"Set to `true` if block corresponds to the canonical chain tip","type":"boolean"},"height":{"description":"Height of the block","type":"integer"},"hash":{"description":"Hash representing the block","type":"string"},"block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"tenure_height":{"description":"The tenure height (AKA coinbase height) of this block","type":"integer"},"index_block_hash":{"description":"The only hash that can uniquely identify an anchored block or an unconfirmed state trie","type":"string"},"parent_block_hash":{"description":"Hash of the parent block","type":"string"},"parent_index_block_hash":{"description":"Index block hash of the parent block","type":"string"},"burn_block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"burn_block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"burn_block_hash":{"description":"Hash of the anchor chain block","type":"string"},"burn_block_height":{"description":"Height of the anchor chain block","type":"integer"},"miner_txid":{"description":"Anchor chain transaction ID","type":"string"},"tx_count":{"description":"Number of transactions included in the block","type":"integer"},"execution_cost_read_count":{"description":"Execution cost read count.","type":"integer"},"execution_cost_read_length":{"description":"Execution cost read length.","type":"integer"},"execution_cost_runtime":{"description":"Execution cost runtime.","type":"integer"},"execution_cost_write_count":{"description":"Execution cost write count.","type":"integer"},"execution_cost_write_length":{"description":"Execution cost write length.","type":"integer"}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}
```

## Get signer signatures for block

> Retrieves the signer signatures (an array of signature byte strings) in a single block

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Blocks","description":"Read-only endpoints to obtain Stacks block details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v2/blocks/{height_or_hash}/signer-signatures":{"get":{"operationId":"get_signer_signatures_for_block","summary":"Get signer signatures for block","tags":["Blocks"],"description":"Retrieves the signer signatures (an array of signature byte strings) in a single block","parameters":[{"schema":{"minimum":0,"default":500,"maximum":1000,"title":"Limit","type":"integer"},"in":"query","name":"limit","required":false,"description":"Results per page"},{"schema":{"minimum":0,"default":0,"title":"Offset","type":"integer"},"in":"query","name":"offset","required":false,"description":"Result offset"},{"schema":{"anyOf":[{"type":"string","enum":["latest"]},{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},{"title":"Block height","description":"Block height","type":"integer"}]},"in":"path","name":"height_or_hash","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["limit","offset","total","results"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"results":{"type":"array","items":{"description":"Array of hex strings representing the block's signer signature","type":"string"}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}
```

## Get blocks by tenure

> Retrieves blocks confirmed in a block tenure

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Blocks","description":"Read-only endpoints to obtain Stacks block details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v2/block-tenures/{tenure_height}/blocks":{"get":{"operationId":"get_tenure_blocks","summary":"Get blocks by tenure","tags":["Blocks"],"description":"Retrieves blocks confirmed in a block tenure","parameters":[{"schema":{"minimum":0,"default":20,"maximum":30,"title":"Limit","type":"integer"},"in":"query","name":"limit","required":false,"description":"Results per page"},{"schema":{"default":0,"maximum":300,"minimum":-300,"title":"Offset","type":"integer"},"in":"query","name":"offset","required":false,"description":"Result offset"},{"schema":{"pattern":"^0x[a-fA-F0-9]{64}$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for block pagination"},{"schema":{"minimum":0,"title":"Block tenure height","type":"integer"},"in":"path","name":"tenure_height","required":true,"description":"Block tenure height"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["limit","offset","total","next_cursor","prev_cursor","cursor","results"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"next_cursor":{"anyOf":[{"description":"Next page cursor","type":"string"},{"type":"null"}]},"prev_cursor":{"anyOf":[{"description":"Previous page cursor","type":"string"},{"type":"null"}]},"cursor":{"anyOf":[{"description":"Current page cursor","type":"string"},{"type":"null"}]},"results":{"type":"array","items":{"type":"object","required":["canonical","height","hash","block_time","block_time_iso","tenure_height","index_block_hash","parent_block_hash","parent_index_block_hash","burn_block_time","burn_block_time_iso","burn_block_hash","burn_block_height","miner_txid","tx_count","execution_cost_read_count","execution_cost_read_length","execution_cost_runtime","execution_cost_write_count","execution_cost_write_length"],"properties":{"canonical":{"description":"Set to `true` if block corresponds to the canonical chain tip","type":"boolean"},"height":{"description":"Height of the block","type":"integer"},"hash":{"description":"Hash representing the block","type":"string"},"block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"tenure_height":{"description":"The tenure height (AKA coinbase height) of this block","type":"integer"},"index_block_hash":{"description":"The only hash that can uniquely identify an anchored block or an unconfirmed state trie","type":"string"},"parent_block_hash":{"description":"Hash of the parent block","type":"string"},"parent_index_block_hash":{"description":"Index block hash of the parent block","type":"string"},"burn_block_time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"integer"},"burn_block_time_iso":{"description":"An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.","type":"string"},"burn_block_hash":{"description":"Hash of the anchor chain block","type":"string"},"burn_block_height":{"description":"Height of the anchor chain block","type":"integer"},"miner_txid":{"description":"Anchor chain transaction ID","type":"string"},"tx_count":{"description":"Number of transactions included in the block","type":"integer"},"execution_cost_read_count":{"description":"Execution cost read count.","type":"integer"},"execution_cost_read_length":{"description":"Execution cost read length.","type":"integer"},"execution_cost_runtime":{"description":"Execution cost runtime.","type":"integer"},"execution_cost_write_count":{"description":"Execution cost write count.","type":"integer"},"execution_cost_write_length":{"description":"Execution cost write length.","type":"integer"}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stacks.co/reference/api/stacks-blockchain-api/blocks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.