# Get blocks across blockchains

Returns a paginated list of blocks from all or specified blockchains.

Endpoint: GET /blocks
Version: 1.0.0
Security: ApiKeyAuth

## Query parameters:

  - `page` (integer)
    Page number for pagination
    Example: 1

  - `limit` (integer)
    Maximum number of items to return
    Example: 20

  - `sort_by` (string)
    Field to sort results by. Use "-" prefix for descending order
    Enum: "number", "-number", "status", "-status"

  - `chain_gids` (array)
    Comma-separated list of chain GIDs to filter blocks by.
    Example: ["eip155:1"]

  - `statuses` (array)
    Comma-separated list of block statuses to include.
    Enum: "new", "fetched", "processed", "confirmed", "reorged"

  - `from_block` (integer)
    Start from this block number (inclusive).
    Example: 18500000

  - `to_block` (integer)
    End at this block number (inclusive).
    Example: 18500100

## Response 200 fields (application/json):

  - `items` (array, required)

  - `items.chain_gid` (string, required)
    Blockchain identifier according to [CAIP-2](https://chainagnostic.org/CAIPs/caip-2).

The chain_gid is a case-sensitive string uniquely identifying a blockchain.
It is composed of:
- namespace — a short identifier describing an ecosystem or standard (e.g. eip155, cosmos)
- reference — an identifier for a specific blockchain within that namespace

Syntax

chain_id = namespace ":" reference
namespace = [-a-z0-9]{3,8}
reference = [-_a-zA-Z0-9]{1,32}


Examples
- eip155:1 — Ethereum mainnet
- eip155:56 — Binance Smart Chain
- cosmos:cosmoshub-4 — Cosmos Hub mainnet
- bip122:000000000019d6689c085ae165831e93 — Bitcoin mainnet
    Example: "eip155:1"

  - `items.number` (integer, required)
    Block number/height on the blockchain
    Example: 18500000

  - `items.hash` (string)
    Block hash identifier unique per blockchain (null if not yet fetched)
    Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

  - `items.status` (string, required)
    Current processing status of the block:
- new: Block has been discovered but not yet fetched
- processed: Block transactions have been analyzed and stored
- confirmed: Block has reached minimum required confirmations
- reorged: Block has been reorganized (chain reorg occurred)
    Enum: "new", "processed", "confirmed", "reorged"

  - `meta` (object, required)

  - `meta.limit` (integer, required)
    Number of items per page
    Example: 20

  - `meta.page` (integer, required)
    Current page number
    Example: 1

  - `meta.total` (integer, required)
    Total number of items available
    Example: 42

  - `meta.total_pages` (integer, required)
    Total number of pages available
    Example: 3

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI reference that identifies the problem type
    Example: "https://docs.vilna.io/apis/problems/invalid-request"

  - `title` (string, required)
    A short, human-readable summary of the problem type
    Example: "Invalid Request"

  - `status` (integer, required)
    The HTTP status code
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem
    Example: "Validation error"

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem
    Example: "/errors?id=XXXXXX-xxxxx"

  - `fields` (array)
    List of invalid fields in the request

  - `fields.name` (string, required)
    The name of the invalid field
    Example: "meta"

  - `fields.reason` (string, required)
    Why this field is invalid
    Example: "Exceeded maximum data size — must not exceed 1000 characters"

## Response default fields (application/problem+json):

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem
    Example: "An unexpected error occurred while processing your request"

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem
    Example: "/errors/1234567890"

  - `status` (integer, required)
    The HTTP status code
    Example: 500

  - `title` (string, required)
    A short, human-readable summary of the problem type
    Example: "Internal Server Error"

  - `type` (string, required)
    A URI reference that identifies the problem type
    Example: "https://api.vilna.io/problems/internal-error"