# Read methods

An Arkiv node answers the standard Ethereum JSON-RPC methods plus three `arkiv_*` methods that read entities. The SDK’s public client calls them for you. Call them directly when you work in a language without an SDK.

| Method | Returns |
| --- | --- |
| [`arkiv_query`](#arkiv_query) | One page of the entities that match a query, and how many match |
| [`arkiv_getEntity`](#arkiv_getentity) | One entity by key, or `null` |
| [`arkiv_getBlockTiming`](#arkiv_getblocktiming) | The current block, its time and the block duration |

The examples send requests to Rabdi’s RPC, `https://rpc.rabdi.db-chain.testnet.arkiv.network`, with your [access key](https://stage.docs.arkiv.network/start-here/access-keys/) at the end of the URL. Its chain ID is `7794095`. Set `ARKIV_ACCESS_KEY` before you run them. Without a key, the requests go to the public RPC, which is heavily rate limited.

<RpcTerms />

## arkiv_query

Finds the entities that match a query and returns the fields you select:

```bash
curl "https://rpc.rabdi.db-chain.testnet.arkiv.network/$ARKIV_ACCESS_KEY" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "arkiv_query",
  "params": [
    "arkiv.schema = str('my-app.posts') AND category = str('news')",
    { "select": { "key": true, "attributes": true }, "limit": "0xa" }
  ]
}
EOF
```

The first parameter is the query. See the [query language](https://stage.docs.arkiv.network/reference/query-language/) for its syntax. Anyone can write entities with any attributes, so filter on your project’s tag or on `$owner`.

The second parameter is optional. Every field in it is optional too:

| Field | Description |
| --- | --- |
| `select` | The fields to return. Defaults to `{ "key": true }` |
| `limit` | The page size, from 1 to 100. Defaults to 100 |
| `offset` | How many matches to skip before the page. Defaults to 0 |

### Select fields

Every `select` field is a boolean, and off unless you set it:

| Field | Returns |
| --- | --- |
| `key` | The entity key. On when you leave out `select` |
| `owner`, `creator` | The owner and the account that created the entity |
| `createdAt`, `updatedAt`, `expiresAt` | Block numbers, as hex |
| `creationFlags` | `{ "readonly", "permissionlessExtension", "raw" }` |
| `attributes` | Every attribute with its value |
| `attributeSchema` | Every attribute’s name, type and `indexed`, without values |
| `count` | How many entities the query matches, as the response’s `count` |

`attributes` also takes an object of names, to return only those: `{ "attributes": { "title": true } }`.

`count` isn’t a field of each entity. It counts every match at the block, whatever the `limit`, and every page repeats it. With `count` as the only field, `data` is empty:

```json
[
  "arkiv.schema = str('my-app.posts') AND category = str('news')",
  { "select": { "count": true } }
]
```

### Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "data": [
      {
        "key": "0x9f2c…",
        "attributes": [
          { "name": "arkiv.schema", "type": "str", "value": "my-app.posts" },
          { "name": "category", "type": "str", "value": "news" },
          { "name": "score", "type": "dec", "value": "4.5" }
        ]
      }
    ],
    "blockNumber": "0x1bc",
    "count": "0x2a"
  }
}
```

An entity holds only the fields you selected. A field you didn’t select is left out, not set to `null`. `blockNumber` is the block the page was read at, and `count` is there only if you selected it.

An attribute’s `type` decides how its `value` is written:

| Type | JSON value |
| --- | --- |
| `bool` | `true` or `false` |
| `i32` | A number |
| `u64`, `u256` | A hex quantity, such as `"0x2a"` |
| `dec` | A decimal string, such as `"4.5"` |
| `str` | A string |
| `addr`, `key`, `bytes` | Hex bytes |

### Paginate

To get the next page, send the same query again with an `offset`. Add `ORDER BY $key ASC` so every page uses one order. This asks for the third page of 10:

```json
[
  "arkiv.schema = str('my-app.posts') ORDER BY $key ASC",
  { "limit": "0xa", "offset": "0x14" }
]
```

Each request reads the latest block. An entity created or deleted between two requests shifts the matches after it, so a row can repeat or be missed. A page with fewer rows than `limit` is the last, and an `offset` past the end returns an empty page. To read every match once, page by key: add `$key > key(0x…)` with the last key of the previous page.

### Errors

The node rejects a query it can’t run with one of these error codes:

| Code | Cause |
| --- | --- |
| `-32001` | The query doesn’t parse. `data` holds the position, what was expected and what was found |
| `-32002` | A condition uses the wrong type for its operator, such as `STARTSWITH` on an `i32`, or `BETWEEN` bounds of two types |
| `-32003` | A value is invalid, such as an `i32` out of range |
| `-32004` | The query goes over a node limit, such as its length or nesting depth |

A `limit` outside 1 to 100 fails with `-32602`, invalid params.

## arkiv_getEntity

Reads one entity by key at the latest block, with every field except `attributeSchema`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "arkiv_getEntity",
  "params": ["0x9f2c…"]
}
```

The result has the shape of an entity in `arkiv_query`. It’s `null` when no live entity has the key: it never existed, or it was deleted or has expired.

## arkiv_getBlockTiming

Takes no parameters and returns the latest block:

```json
{ "current_block": 582143, "current_block_time": 1742721127, "duration": 2 }
```

`current_block_time` is a Unix time in seconds. `duration` is the number of seconds since the previous block.