Hiro Blocks API
The Blocks API from Hiro — 37 operation(s) for blocks.
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts Blocks API
description: Welcome to the API reference overview for the Signer Metrics API.
version: 1.0.3
servers:
- url: https://api.hiro.so/
description: mainnet
- url: https://api.testnet.hiro.so/
description: testnet
tags:
- name: Blocks
paths:
/signer-metrics/v1/blocks:
get:
operationId: getBlocks
summary: Aggregated signer information for most recent blocks
tags:
- Blocks
description: Aggregated signer information for most recent blocks
parameters:
- schema:
type: integer
default: 100
in: query
name: limit
required: true
description: Number of results to return
- schema:
type: integer
default: 0
in: query
name: offset
required: true
description: Number of results to skip
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
required:
- total
- limit
- offset
- results
properties:
total:
type: integer
limit:
type: integer
offset:
type: integer
results:
type: array
items:
type: object
required:
- block_height
- block_hash
- block_time
- index_block_hash
- burn_block_height
- tenure_height
- signer_data
properties:
block_height:
type: integer
block_hash:
type: string
block_time:
description: Unix timestamp in seconds of when the block was mined
type: integer
index_block_hash:
type: string
burn_block_height:
type: integer
tenure_height:
type: integer
signer_data:
description: Signer data can by null if it was not detected by the metrics service
anyOf:
- type: object
required:
- cycle_number
- total_signer_count
- accepted_count
- rejected_count
- missing_count
- accepted_excluded_count
- average_response_time_ms
- block_proposal_time_ms
- accepted_stacked_amount
- rejected_stacked_amount
- missing_stacked_amount
- accepted_weight
- rejected_weight
- missing_weight
properties:
cycle_number:
type: integer
total_signer_count:
description: Total number of signers expected for this block
type: integer
accepted_count:
description: Number of signers that submitted an approval for this block
type: integer
rejected_count:
description: Number of signers that submitted a rejection for this block
type: integer
missing_count:
description: Number of signers that failed to submit any response/vote for this block
type: integer
accepted_excluded_count:
description: Number of signers that submitted an approval but where not included in time by the miner (this is a subset of the accepted_count)
type: integer
average_response_time_ms:
description: Average time duration (in milliseconds) taken by signers to submit a response for this block (tracked best effort)
type: number
block_proposal_time_ms:
description: Unix timestamp in milliseconds of when the block was first proposed (tracked best effort)
type: number
accepted_stacked_amount:
description: Sum of total STX stacked of signers who approved the block
type: string
rejected_stacked_amount:
description: Sum of total STX stacked of signers who rejected the block
type: string
missing_stacked_amount:
description: Sum of total STX stacked of missing signers
type: string
accepted_weight:
description: Sum of voting weight of signers who approved the block (based on slots allocated to each signer proportional to stacked amount)
type: integer
rejected_weight:
description: Sum of voting weight of signers who rejected the block
type: integer
missing_weight:
description: Sum of voting weight of missing signers
type: integer
- type: 'null'
/signer-metrics/v1/blocks/{height_or_hash}:
get:
operationId: getBlock
summary: Aggregated signer information for a block
tags:
- Blocks
description: Aggregated signer information for a block
parameters:
- schema:
anyOf:
- type: string
enum:
- latest
- pattern: ^(0x)?[a-fA-F0-9]{64}$
title: Block hash
description: Block hash
examples:
- '0xdaf79950c5e8bb0c620751333967cdd62297137cdaf79950c5e8bb0c62075133'
type: string
- title: Block height
description: Block height
examples:
- 777678
type: integer
in: path
name: height_or_hash
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
required:
- block_height
- block_hash
- block_time
- index_block_hash
- burn_block_height
- tenure_height
- signer_data
properties:
block_height:
type: integer
block_hash:
type: string
block_time:
description: Unix timestamp in seconds of when the block was mined
type: integer
index_block_hash:
type: string
burn_block_height:
type: integer
tenure_height:
type: integer
signer_data:
description: Signer data can by null if it was not detected by the metrics service
anyOf:
- type: object
required:
- cycle_number
- total_signer_count
- accepted_count
- rejected_count
- missing_count
- accepted_excluded_count
- average_response_time_ms
- block_proposal_time_ms
- accepted_stacked_amount
- rejected_stacked_amount
- missing_stacked_amount
- accepted_weight
- rejected_weight
- missing_weight
properties:
cycle_number:
type: integer
total_signer_count:
description: Total number of signers expected for this block
type: integer
accepted_count:
description: Number of signers that submitted an approval for this block
type: integer
rejected_count:
description: Number of signers that submitted a rejection for this block
type: integer
missing_count:
description: Number of signers that failed to submit any response/vote for this block
type: integer
accepted_excluded_count:
description: Number of signers that submitted an approval but where not included in time by the miner (this is a subset of the accepted_count)
type: integer
average_response_time_ms:
description: Average time duration (in milliseconds) taken by signers to submit a response for this block (tracked best effort)
type: number
block_proposal_time_ms:
description: Unix timestamp in milliseconds of when the block was first proposed (tracked best effort)
type: number
accepted_stacked_amount:
description: Sum of total STX stacked of signers who approved the block
type: string
rejected_stacked_amount:
description: Sum of total STX stacked of signers who rejected the block
type: string
missing_stacked_amount:
description: Sum of total STX stacked of missing signers
type: string
accepted_weight:
description: Sum of voting weight of signers who approved the block (based on slots allocated to each signer proportional to stacked amount)
type: integer
rejected_weight:
description: Sum of voting weight of signers who rejected the block
type: integer
missing_weight:
description: Sum of voting weight of missing signers
type: integer
- type: 'null'
/extended/v1/block/:
get:
operationId: get_block_list
summary: Get recent blocks
tags:
- Blocks
description: "**NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks).\n\n Retrieves a list of recently mined blocks\n\n If you need to actively monitor new blocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates."
parameters:
- schema:
minimum: 0
default: 20
maximum: 30
title: Limit
type: integer
in: query
name: limit
required: false
description: max number of blocks to fetch
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: Result offset
deprecated: true
responses:
'200':
description: GET request that returns blocks
content:
application/json:
schema:
title: BlockListResponse
description: GET request that returns blocks
type: object
properties:
limit:
type: integer
example: 20
offset:
type: integer
example: 0
total:
type: integer
example: 1
results:
type: array
items:
title: Block
description: A block
type: object
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: number
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
burn_block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: number
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
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
txs:
description: List of transactions included in the block
type: array
items:
description: Transaction ID
type: string
parent_microblock_hash:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: string
parent_microblock_sequence:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: integer
microblocks_accepted:
description: List of microblocks that were accepted in this anchor block. Not every anchored block will have a accepted all (or any) of the previously streamed microblocks. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblocks_streamed:
description: List of microblocks that were streamed/produced by this anchor block's miner. This list only includes microblocks that were accepted in the following anchor block. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblock_tx_count:
description: List of txs counts in each accepted microblock
type: object
additionalProperties:
type: integer
required:
- canonical
- height
- hash
- block_time
- block_time_iso
- tenure_height
- index_block_hash
- parent_block_hash
- burn_block_time
- burn_block_time_iso
- burn_block_hash
- burn_block_height
- miner_txid
- execution_cost_read_count
- execution_cost_read_length
- execution_cost_runtime
- execution_cost_write_count
- execution_cost_write_length
- txs
- parent_microblock_hash
- parent_microblock_sequence
- microblocks_accepted
- microblocks_streamed
- microblock_tx_count
required:
- limit
- offset
- total
- results
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v1/block/by_height/{height}:
get:
operationId: get_block_by_height
summary: Get block by height
tags:
- Blocks
description: "**NOTE:** This endpoint is deprecated in favor of [Get block](/api/get-block).\n\n Retrieves block details of a specific block at a given block height"
parameters:
- schema:
minimum: 0
type: integer
example: 10000
in: path
name: height
required: true
description: Height of the block
deprecated: true
responses:
'200':
description: A block
content:
application/json:
schema:
title: Block
description: A block
type: object
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: number
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
burn_block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: number
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
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
txs:
description: List of transactions included in the block
type: array
items:
description: Transaction ID
type: string
parent_microblock_hash:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: string
parent_microblock_sequence:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: integer
microblocks_accepted:
description: List of microblocks that were accepted in this anchor block. Not every anchored block will have a accepted all (or any) of the previously streamed microblocks. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblocks_streamed:
description: List of microblocks that were streamed/produced by this anchor block's miner. This list only includes microblocks that were accepted in the following anchor block. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblock_tx_count:
description: List of txs counts in each accepted microblock
type: object
additionalProperties:
type: integer
required:
- canonical
- height
- hash
- block_time
- block_time_iso
- tenure_height
- index_block_hash
- parent_block_hash
- burn_block_time
- burn_block_time_iso
- burn_block_hash
- burn_block_height
- miner_txid
- execution_cost_read_count
- execution_cost_read_length
- execution_cost_runtime
- execution_cost_write_count
- execution_cost_write_length
- txs
- parent_microblock_hash
- parent_microblock_sequence
- microblocks_accepted
- microblocks_streamed
- microblock_tx_count
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v1/block/by_burn_block_height/{burn_block_height}:
get:
operationId: get_block_by_burn_block_height
summary: Get block by burnchain height
tags:
- Blocks
description: "**NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks).\n\n Retrieves block details of a specific block for a given burn chain height"
parameters:
- schema:
minimum: 0
type: integer
example: 744603
in: path
name: burn_block_height
required: true
description: Height of the burn chain block
deprecated: true
responses:
'200':
description: A block
content:
application/json:
schema:
title: Block
description: A block
type: object
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: number
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
burn_block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: number
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
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
txs:
description: List of transactions included in the block
type: array
items:
description: Transaction ID
type: string
parent_microblock_hash:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: string
parent_microblock_sequence:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: integer
microblocks_accepted:
description: List of microblocks that were accepted in this anchor block. Not every anchored block will have a accepted all (or any) of the previously streamed microblocks. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblocks_streamed:
description: List of microblocks that were streamed/produced by this anchor block's miner. This list only includes microblocks that were accepted in the following anchor block. Microblocks that were orphaned are not i
# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-blocks-api-openapi.yml