blocks

The blocks query retrieves a paginated list of blockchain blocks with comprehensive filtering and ordering capabilities.

It returns a BlockList object containing an array of Block objects that meet the specified filtering criteria.

Schema Definition

blocks(
  first: Int = 10
  skip: Int = 0
  where: BlockFilter
  orderBy: BlockOrderBy
  orderDirection: Ordering
): BlockList!

Arguments

Argument	Type	Description
first	Int = 10 scalar	Maximum number of blocks to retrieve per page. Maximum value is 100.
skip	Int = 0 scalar	Number of blocks to bypass before assembling the page. Set to the first value from the previous page for offset pagination.
where	BlockFilter input	Specifies subsets of block data to be retrieved.
orderBy	BlockOrderBy enum	Sets how the list of blocks is ordered.
orderDirection	Ordering enum	Sets the direction in which the list of blocks is ordered.

Return Type

BlockList object

Common Use Cases

• Display detailed block information in block explorer applications.
• Conduct historical analysis of block data using various filters such as block number ranges, timestamps, and transaction counts.
• Monitor for unusual or significant on-chain activity such as blocks with high transaction volumes or gas usage.
• Build custom blockchain data pipelines with filtered block ranges.

Example

Query

Get 5 Most Recent Blocks

query Get5MostRecentBlocks($first: Int, $orderBy: BlockOrderBy, $orderDirection: Ordering) {
  blocks(first: $first, orderBy: $orderBy, orderDirection: $orderDirection) {
    entries {
      number
      timestamp
      size
      gasLimit
      gasUsed
      hash
    }
  }
}

Variables

{
  "first": 5,
  "orderBy": "NUMBER",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "blocks": {
      "entries": [
        {
          "number": 142934353,
          "timestamp": 1761467483,
          "size": 17819,
          "gasLimit": 40000000,
          "gasUsed": 12861377,
          "hash": "0x968ae3cd572c782192b122d7d579672e0237aee0d644a90b591d4f5b7f745b95"
        },
        {
          "number": 142934352,
          "timestamp": 1761467481,
          "size": 12601,
          "gasLimit": 40000000,
          "gasUsed": 36751745,
          "hash": "0x513896b1480a75493aebf1c53e65c2c247a14036a49e782a635bcc9bbe3b02fd"
        },
        {
          "number": 142934351,
          "timestamp": 1761467479,
          "size": 14156,
          "gasLimit": 40000000,
          "gasUsed": 13804391,
          "hash": "0x68ad70ff88c833981ffed861569e0671b205ec9d63d09426876536564da66048"
        },
        {
          "number": 142934350,
          "timestamp": 1761467477,
          "size": 11536,
          "gasLimit": 40000000,
          "gasUsed": 12190918,
          "hash": "0x48c9ac300357d4b0a441a0173a5271cf3512d813f0567765a249d7b457a817c6"
        },
        {
          "number": 142934349,
          "timestamp": 1761467475,
          "size": 15769,
          "gasLimit": 40000000,
          "gasUsed": 9269063,
          "hash": "0x79a4c9f0f7d0fa7df0788918e656ada4b7938d127e0a035eac72ca0fcea6d608"
        }
      ]
    }
  }
}

Implementation Notes

note

• The default first value is 10 transactions. OneSource enforces a maximum first value of 100. Adjust based on your UI needs.
• Use skip for offset-based pagination. To get the next page, use a skip value equal to the previous first value.
• All range filters use Gte (greater than or equal to) and Lte (less than or equal to) suffixes for inclusive ranges.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.
• For ordering use ASC for ascending (oldest first) and DESC for descending (newest first).
• Each block object in the returned BlockList array supports nested transactions() with its own pagination for fetching transactions within that block.