blocks_by_height

Overview

Fetch a block by its block height together with block metadata, and optionally expand the block into the transactions it contains. This is the right endpoint when you already know the block you want and need to anchor application logic to block boundaries instead of individual transaction hashes.

Endpoint

GET /v1/blocks/by_height/{block_height}

block_height identifies the consensus block, not a single ledger version. One block can include multiple transactions, so this endpoint is useful for explorers, replay jobs, and monitoring systems that checkpoint work at block level.

Response Shape

With with_transactions=false, the response stays compact and is best for checkpointing or timeline views:

{
  "block_height": "1000000",
  "block_hash": "0xd8f4f8cb...",
  "first_version": "10240841",
  "last_version": "10240863",
  "block_timestamp": "1661961900602338",
  "transactions": null
}

When with_transactions=true, the response also includes the committed transactions inside that block. That is useful for replay or block explorer detail pages, but it can grow large on busy blocks.

Code Examples

# Get block metadata only
curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/blocks/by_height/1000000" \
  -H "Accept: application/json"

# Get block with all transactions
curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/blocks/by_height/1000000?with_transactions=true" \
  -H "Accept: application/json"

When to Enable with_transactions

• Set it to false when you only need block boundaries, timestamps, or version ranges.
• Set it to true when your worker will immediately process the block's transactions and you want to avoid extra follow-up lookups.
• Prefer metadata-only reads for polling or checkpoint loops, then expand only the blocks you actually need to inspect in detail.

Practical Guidance

• Store both block_height and the first_version/last_version range if you plan to resume block-based indexing later. Read block_timestamp from the metadata response rather than assuming a generic timestamp field.
• Busy blocks can return large payloads, so avoid defaulting to with_transactions=true in lightweight monitoring jobs.
• If your UI deep-links into one transaction from the block, pair this endpoint with transactions_by_hash for the detailed drill-down.
• Treat block height and ledger version as different coordinates. A version points to one transaction; a block height points to a grouped execution boundary.

Related Endpoints

• accounts_transactions for sender-scoped history
• transactions_by_hash for one known transaction