Quick Start

A quick introduction to using the Explorer running on Snowflake SQL.

Data Caveats

  • SQL: Our Explorer data is powered by Snowflake SQL.

  • Timestamps: All timestamps are in Coordinated Universal Time (UTC).

  • Prices: All prices-related data are in USD denomination unless otherwise stated

  • Address Casing: All EVM addresses are in lower casing.

  • Native token: Native tokens are presented by zero address for the respective chain. E.g for Ethereum and most EVM chains: 0x0000000000000000000000000000000000000000, Tron: T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

Prerequisites

Before you get started, we assume you already have:

  • Create a query that you would like to run programmatically. If you haven't done so, head over to Allium App and create a query. For your convenience, here's an example query you can use:

SELECT * FROM ethereum.raw.blocks LIMIT 100
  • Have a local environment set up where you can run cURL, python or js code.

TL;DR

  1. Get your API key, and query ID.

  2. Run the following to get started quickly, run your query and retrieve the results:

run_query_async.py
import time, requests

QUERY_ID = "<your query ID>"
API_KEY = "<your api key here>"

response = requests.post(
    f"https://api.allium.so/api/v1/explorer/queries/{QUERY_ID}/run-async",
    json={"parameters": {}, "run_config": {"limit": 1000}},
    headers={"X-API-Key": API_KEY},
    timeout=10,
)
# If you get an error, print out response.json() to learn more.
run_id = response.json()["run_id"]
print(f"Query run created with ID: {run_id}")

polling_interval, start, timeout = 1, time.time(), 20 * 60  # 20min timeout
while time.time() < start + timeout:
    response = requests.get(
        f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/status",
        headers={"X-API-Key": API_KEY},
        timeout=10,
    )
    run_status = response.json()
    if run_status not in ["created", "queued", "running"]:
        break
    print(f"Current status: {run_status}. Waiting {polling_interval}s...")
    time.sleep(polling_interval)

if run_status == "success":
    response = requests.get(
        f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/results?f=json",
        headers={"X-API-Key": API_KEY},
    )
    results = response.json()
    print(
        f"Query returned {len(results['data'])} rows, with "
        f"fields: {', '.join(column.get('name') for column in results['meta']['columns'])}"
    )
elif run_status == "failed":
    response = requests.get(
        f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/error",
        headers={"X-API-Key": API_KEY},
    )
    error_message = response.json()
    print(
        f"Query failed with error: {error_message}"
    )
else:
    print(f"Query run finished with status: {run_status}. No results.")

If you see a 4XX or 5XX response error, you can learn more about the error by looking at the JSON response body. In python, you can do that by doing:

print(response.json())

Getting started

With our API, you can easily query Allium's data and retrieve results using simple HTTP requests. To get started, follow these steps:

1. Get your API key

To use the API, you will need to create an API key for yourself. This key will allow you to authenticate your requests and access the API endpoints.

Click here to learn more on how to get your API key or follow the video below.

As demonstrated in the video above, to generate your API key:

  • Go to the query you wish to use the API to run.

  • On the top right-hand corner of the screen, click the icon to open up the query configuration drawer.

  • If you have not done so, click 'Generate token' to generate a new API key.

  • For your convenience, click on the copy icon on the right of the API key to copy your key. Save this key for later.

The API key is generated per account, and is used for all the queries accessible by your account.

2. Get your query ID

You will also need your query ID in order to identify the query you wish to run.

Click here to learn more on how to get your Query ID or follow the video below.

As seen in the video above, to get your query ID:

  • Go to the query you wish to use the API to run.

  • On the top right-hand corner of the screen, click the icon to open up the query configuration drawer.

  • Click on the copy icon on the right of the Query ID field to copy your ID. Save this ID for later.

Your query ID can also be found in your query page URL.

3. Run your query asynchronously

Now we want to run your query asynchronously.

In a python script, run:

import requests

QUERY_ID = "<your query ID here>"
API_KEY = "<your api key here>"

response = requests.post(
    f"https://api.allium.so/api/v1/explorer/queries/{QUERY_ID}/run-async",
    json={
        "parameters": {},
        "run_config": {
            "limit": 1000,
        }
    },
    headers={
        "X-API-Key": API_KEY
    },
)

result = response.json()
print(result)

Ensure that you have replaced query_id with your query ID and api_key with your API key.

Add the "limit" field to "run_config" allows you to increase your query's row limit. By default, the limit is set to 10000. To increase it beyond that, use the limit field. With Explorer API, the max limit allowed is 250000.

If you have any parameter fields in your query, add them to the parameters field of the POST request body.

If you request was successful, your query will now be running asynchronously and you will get a response with your query run ID, for example:

{ "run_id": "c7UViykJloFAUY2pwFjd" }

Keep this query run ID for the next step.

4. Check your query run status

Next, we want to check for the status of your query run using the query run ID returned in the previous step to identify your query run:

Continuing from the previous script:

...

result = response.json()
print(result)

run_id = result["run_id"]

response = requests.get(