Overview

When using the endpoints of fundamental APIs, like Blocks API or Logs API, you must specify the block or time range you want to retrieve data from. Ranges can be set via block_number_start and block_number_end or timestamp_start and timestamp_end. Additionally, you can extract data from a particular block by specifying its block_hash.

Block Number Range

When you know specific block numbers, you can utilize the block_number_start and block_number_end parameters. These are instructions for APIs to determine which blocks to scan on the blockchain. Remember that the value of block_number_end must always be greater than the one of block_number_start.

These parameters accept int256 values. You can also set block_number_end to the latest block, by specify the value latest in it. To obtain data from the latest block on a chain, refer to the Get Latest Block endpoint for details. Alternatively, the parameters take on negative numbers as values. For instance, setting it to block_number_start=-1000 means the starting point is 1000 blocks away from the latest block.

To scan from block 1000 to block 2000, set the block_number_start and block_number_end parameters in the request like so:

?block_number_start=1000&block_number_end=2000

To scan every single block, specify 0 in block_number_start and latest in block_number_end like so:

?block_number_start=0&block_number_end=latest

Knowing the block number, extract its time and hash by passing the same block number to block_number_start and block_number_end like this:

?block_number_start=17087509&block_number_end=17087509

or like this:

?block_number_start=-1&block_number_end=-1

When unsure what block range to input, try using a range of -100000 to latest. We would recommend against setting block_number_start to 0 and block_number_end to latest unless it is exactly what you require. Otherwise, you will quickly reach your limit due to retrieval from the genesis to the latest blocks, which is years of data.

Timestamp Range

Knowing the time of block production, you may set the range via the timestamp_start and timestamp_end parameters. Timestamps are represented in UNIX time, so it is necessary to convert the desired time period to UNIX time format. Many programming languages support libraries for datetime conversion. As an alternative, you can convert the time here (opens in a new tab).

As an example, if you need the information on a contract dated from January 1st, 2022, 00:00 GMT to January 31st, 2022, 23:59 GMT, the actual parameter values would be 1640995200 and 1643673540 in UNIX time. So the values of parameters should be specified like so:

?timestamp_start=1640995200&timestamp_end=1643673540

Knowing the timestamp of a block, extract its block number and hash by passing the same timestamp value to timestamp_start and timestamp_end like so:

?timestamp_start=1681991771&timestamp_end=1681991771

Block Hash

To obtain the data of a specific block, provide its block_hash as a parameter value. For instance, the hash of block 1337 (opens in a new tab) on Ethereum Mainnet, which is 0x0c195cccdaf1c289879187a819ae8caed341fd5568e32d98b584c37dc09c59e7, would structure the parameter like so:

?block_hash=0x0c195cccdaf1c289879187a819ae8caed341fd5568e32d98b584c37dc09c59e7

Offset & Limit

The offset and limit parameters are used for pagination and limitation respectively when retrieving data on a particularly active smart contract. When sending requests via Postman, the response always begins with key-value pairs within the given range, containing useful information:

"range": {
  "has_more": true,
  "start_block": 1,
  "end_block": 6946724,
  "next_offset": "000000000069e99f-000a-00000001"
}

The key-value pair "has_more": true means there are more than 1000 results on that smart contract in a given period. To see the next page, set the offset parameter to the same value as in "range": {"next_offset": "000000000069e99f-000a-00000001"} in the previous response, which is basically the id of the last item on the current page:

?offset=000000000069e99f-000a-00000001

The limit parameter can be of use when expecting a large number of items in the response. To limit your request to 50 items, specify the parameter as follows:

?limit=50

Range options via Parsiq JS Client

Parsiq JS Client supports the following range parameters: limit, offset, and batchSize. The offset parameter is used for pagination. The limit parameter defines the maximum amount of items to be shown in the response, whereas the batchSize defines a part or batch of items. If you set limit to 500 and batchSize to 100, you might expect to receive a maximum of 500 items in five batches of 100 items each. In theory, it is possible to use limit together with batchSize, but it is recommended to focus mainly on limit, as the number of range options will affect the final CU cost. The following example shows how range options can be passed via JS Client:

{
  limit: 500,
  offset: '000000000069e99f-000a-00000001',
  batchSize: 100
}