---
title: ListBlocksRequest
description: ListBlocksRequest lists blocks with pagination and filtering.
source_url:
  html: https://thru.org/docs/api-ref/grpc/messages/thru/services/v1/list-blocks-request/
  md: https://thru.org/docs/api-ref/grpc/messages/thru/services/v1/list-blocks-request.md
---

# ListBlocksRequest

ListBlocksRequest lists blocks with pagination and filtering.

Returns blocks ordered from latest slot to earliest (slot DESC) by default. Supports filtering on block header and footer fields using CEL expressions.

Available fields for filtering:

Header fields:

- block.header.slot (uint64): Block slot number
- block.header.version (uint32): Block version number
- block.header.start\_slot (uint64): Start slot for block production
- block.header.producer.value (bytes): Block producer’s public key
- block.header.expiry\_after (uint32): Expiry duration in slots
- block.header.expiry\_timestamp (google.protobuf.Timestamp): Expiry timestamp
- block.header.max\_block\_size (uint32): Maximum block size in bytes
- block.header.max\_compute\_units (uint64): Maximum compute units allowed
- block.header.max\_state\_units (uint32): Maximum state units allowed
- block.header.bond\_amount\_lock\_up (uint64): Bond amount lock-up for block production
- block.header.price (uint64): Block production price
- block.header.block\_hash.value (bytes): Block hash
- block.header.header\_signature.value (bytes): Header signature
- block.header.block\_time (google.protobuf.Timestamp): Block timestamp

Footer fields:

- block.footer.signature.value (bytes): Block signature
- block.footer.status (int32): Block execution status (2 = EXECUTION\_STATUS\_EXECUTED)
- block.footer.consumed\_compute\_units (uint64): Total compute units consumed by all transactions
- block.footer.consumed\_state\_units (uint32): Total state units consumed by all transactions
- block.footer.attestor\_payment (uint64): Payment to attestors for block validation

Consensus status:

- block.consensus\_status (int32): Consensus status (always CONSENSUS\_STATUS\_INCLUDED for persisted blocks)

Available CEL functions:

- has(field): Check if optional field exists
- uint(value): Convert to uint type
- int(value): Convert to int type
- bytes(value): Convert to bytes type
- timestamp(value): Convert to timestamp type
- duration(value): Convert to duration type

Available filter parameters (accessible via params.\* in expressions):

- params.slot (uint64): Slot number for filtering
- params.u64 (uint64): Generic uint64 parameter
- params.producer (bytes): Producer public key for filtering

Filter examples:

1. Filter by specific slot: filter.expression = “block.header.slot == uint(1234)”

2. Filter by slot range: filter.expression = “block.header.slot >= uint(1000) && block.header.slot <= uint(2000)”

3. Filter by slot using parameter: filter.expression = “block.header.slot == params.slot” filter.params\[“slot”].uint\_value = 1234

4. Filter by block version: filter.expression = “block.header.version == uint(1)”

5. Filter by producer (using parameter): filter.expression = “block.header.producer.value == params.producer” filter.params\[“producer”].bytes\_value = <32-byte producer pubkey>

6. Filter by max compute units: filter.expression = “block.header.max\_compute\_units > uint(1000000)” filter.expression = “block.header.max\_compute\_units >= uint(0) && block.header.max\_compute\_units <= uint(10000000)”

7. Filter by max state units: filter.expression = “block.header.max\_state\_units > uint(0)”

8. Filter by price: filter.expression = “block.header.price >= uint(0)” filter.expression = “block.header.price > uint(1000)”

9. Filter by start\_slot: filter.expression = “block.header.start\_slot <= uint(5000)”

10. Filter by expiry\_after: filter.expression = “block.header.expiry\_after > uint(0)”

11. Filter by max\_block\_size: filter.expression = “block.header.max\_block\_size >= uint(1000000)”

12. Filter by execution status: filter.expression = “block.footer.status == int(2)” // EXECUTION\_STATUS\_EXECUTED

13. Filter by consumed compute units: filter.expression = “block.footer.consumed\_compute\_units > uint(0)” filter.expression = “block.footer.consumed\_compute\_units >= uint(100) && block.footer.consumed\_compute\_units <= uint(1000000)”

14. Filter by consumed state units: filter.expression = “block.footer.consumed\_state\_units >= uint(0)” filter.expression = “block.footer.consumed\_state\_units > uint(10)”

15. Check for footer signature existence: filter.expression = “has(block.footer.signature)”

16. Check for footer existence: filter.expression = “has(block.footer)”

17. Check for producer existence: filter.expression = “has(block.header.producer)”

18. Check for block hash existence: filter.expression = “has(block.header.block\_hash)”

19. Check for header signature existence: filter.expression = “has(block.header.header\_signature)”

20. Check for expiry timestamp existence: filter.expression = “has(block.header.expiry\_timestamp)”

21. Check for block time existence: filter.expression = “has(block.header.block\_time)”

22. Combine multiple header conditions with AND: filter.expression = “block.header.slot >= uint(1000) && block.header.max\_compute\_units > uint(1000000)”

23. Combine multiple footer conditions with AND: filter.expression = “block.footer.consumed\_compute\_units > uint(0) && block.footer.consumed\_state\_units > uint(0)”

24. Combine header and footer conditions: filter.expression = “block.header.slot >= uint(1000) && block.footer.consumed\_compute\_units > uint(100000)”

25. Combine multiple conditions with OR: filter.expression = “block.header.slot == uint(100) || block.header.slot == uint(200)” filter.expression = “block.footer.consumed\_compute\_units > uint(1000000) || block.footer.consumed\_state\_units > uint(10000)”

26. Complex combined filters: filter.expression = “(block.header.slot >= uint(1000) && block.header.slot <= uint(2000)) || block.footer.consumed\_compute\_units > uint(5000000)”

27. Use inequality operators: filter.expression = “block.header.max\_compute\_units < uint(10000000)” filter.expression = “block.header.max\_compute\_units <= uint(10000000)” filter.expression = “block.header.price >= uint(100)” filter.expression = “block.footer.consumed\_compute\_units != uint(0)”

28. Combine has() with value checks: filter.expression = “has(block.header.producer) && block.header.producer.value == params.producer” filter.params\[“producer”].bytes\_value = <32-byte producer pubkey>

29. Filter by multiple resource limits: filter.expression = “block.header.max\_compute\_units > uint(1000000) && block.header.max\_state\_units > uint(1000) && block.header.max\_block\_size > uint(1000000)”

30. Filter blocks with high resource consumption: filter.expression = “block.footer.consumed\_compute\_units > uint(block.header.max\_compute\_units / 2)”

Note: All filters are pushed down to SQL for optimal performance where possible. When SQL pushdown is not possible, filters are evaluated in-memory on fetched results.

**Package:** `thru.services.v1`

## Fields

| Field | Type | # | Description |
| - | - | - | - |
| `filter` | [`thru.common.v1.Filter`](https://thru.org/docs/api-ref/grpc/messages/thru/common/v1/filter.md) | 1 · optional | CEL filter expression (OPTIONAL). See message documentation for examples. |
| `page` | [`thru.common.v1.PageRequest`](https://thru.org/docs/api-ref/grpc/messages/thru/common/v1/page-request.md) | 2 · optional | |
| `view` | [`thru.core.v1.BlockView`](https://thru.org/docs/api-ref/grpc/messages/thru/core/v1/block-view.md) | 3 · optional | |
| `min_consensus` | [`thru.common.v1.ConsensusStatus`](https://thru.org/docs/api-ref/grpc/messages/thru/common/v1/consensus-status.md) | 4 · optional | |