Skip to main content

blockCount

The blockCount query returns the total number of blockchain blocks that match specified filter criteria.

It returns a UInt64 scalar value representing the count of blocks without retrieving the full block data, making it efficient for analytics, metrics dashboards, and pagination calculations.

Schema Definition​

blockCount(
  where: BlockFilter
): UInt64!

Arguments​

ArgumentTypeDescription
whereBlockFilter inputSpecifies subsets of block data to be retrieved

Return Type​

UInt64 scalar​

Common Use Cases​

  • Calculate total blocks produced within a specific time range for network analytics.
  • Display blockchain growth metrics and statistics in dashboard applications.
  • Monitor network activity by tracking block production rates over time.
  • Generate historical reports on block production and network usage patterns.
  • Validate data availability for specific block ranges before performing detailed queries.

Example​

Query​

Count Blocks Produced in the Last 7 Days​

query CountRecentBlocks($timestampGte: UInt64!) {
  blockCount(where: { timestampGte: $timestampGte })
}

Variables​

{
  "timestampGte": "1730467200"
}

Response​

{
  "data": {
    "blockCount": 10234
  }
}

Implementation Notes​

note
  • The blockCount query is significantly more efficient than retrieving full block data when you only need the count.
  • All range filters use Gte (greater than or equal to) and Lte (less than or equal to) suffixes for inclusive ranges.
  • Values for timestamp fields in BlockFilter are Unix timestamps in seconds.
  • The returned count is a UInt64 value represented as a string to ensure precision in JavaScript environments.
  • Use blockCount in combination with the blocks query to calculate total pages for pagination.
  • Filters can be combined to create complex queries (e.g., blocks within a time range with specific gas usage thresholds).