> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> BlockDB Historic REST API — cursor-based, pull-based blockchain data delivery for EVM datasets. Low-latency and paginated.

## Why Use the REST API

* Sub-second access to any dataset supported by the [EVM API suite](/api-reference/overview/home).
* Works behind outbound-only firewalls—no need to expose webhooks.
* Fine-grained filters reduce egress costs; pull only the chains, blocks, or pools you need.

## Core Concepts

* **Endpoints:** Each dataset has a dedicated path (e.g., `/evm/raw/blocks`, `/evm/prices/spot/crypto/ohlc`). All requests are `POST`.
* **Pagination:** Responses contain `cursor` and `count`. Pass the `cursor` from the previous response to request the next page.
* **Ordering:** Use range filters (`range.from`/`range.to`, `_updated_at` windows, sequence numbers) to advance chronologically.
* **Authentication:** API keys (`Authorization: Bearer <API_KEY>`), managed in [dashboard.blockdb.io](https://dashboard.blockdb.io). Rotate or revoke keys per your security policy.

## Example Poller

```bash theme={null}
curl -X POST https://api.blockdb.io/v1/evm/raw/blocks \
  -H "Authorization: Bearer $BLOCKDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": 1,
    "range": {"from": 19000000},
    "fields": ["number","hash","timestamp","_tracing_id"],
    "cursor": "'$CURSOR'"
  }'
```

Pseudo-loop:

1. Call the endpoint with `cursor=null` to seed the stream.
2. Persist the returned `cursor` and latest `_updated_at`.
3. Re-run every few seconds/minutes; include `cursor` to continue where you left off.
4. On failure, replay using the last committed cursor (idempotent).

## Best Practices

* **Backoff:** Implement exponential backoff and respect rate limits documented in your contract.
* **Schema evolution:** Subscribe to [Schema Governance](/data-catalog/overview/schema-governance) so pollers can handle new fields gracefully.
* **Verification:** Periodically reconcile sampled `_tracing_id` values and block anchors with on-chain data or your archival copies.
* **Upserts:** Merge by dataset-specific key + `_tracing_id` to avoid duplication.

<Callout icon="lightbulb" color="#3B82F6" iconType="regular">
  Use separate pollers per dataset family (ledger, pricing, lineage) to prevent one noisy workload from blocking another.
</Callout>