Quickstart

A quick introduction to using the Explorer API

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.

Getting your API key from Allium App

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.

Getting your Query ID from Allium App

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(
    f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/status",
    headers={
        "X-API-Key": API_KEY
    },
)

run_status = response.json()
print(run_status) # Possible values: created, queued, running, success, failed, canceled

The return response will indicate the current status of your query. Possible values are: created, queued, running, success, failed, canceled. When your query run status is success, your query run has successfully completed and you may retrieve the query run's results.

5. Retrieve your query run results

Finally, we want to retrieve the results of the query run. To do so:

Continuing from the previous script:

...

run_status = response.json()
print(run_status) # Possible values: created, queued, running, success, failed, canceled

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
        },
    )
  
    run_results = response.json()
    print(run_results)

The response will contain your query run results formatted as JSON data.

With these simple steps, you can start exploring blockchain data and extracting valuable insights using our Explorer API. To learn more about Explorer API, check out the other sections or take a look at the OpenAPI docs. We look forward to seeing what you'll build with our API!

If you have any questions, do not hesitate to reach out to Paul!

Last updated