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

Get your API key, and query ID.
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.")

const QUERY_ID = "<your query ID here>";
const API_KEY = "<your api key here>";
const HEADERS = {
  "Content-Type": "application/json",
  "X-API-KEY": API_KEY,
};

const response = await fetch(
  `https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async`,
  {
    method: "POST",
    body: JSON.stringify({
      parameters: {},
      run_config: {
        limit: 1000,
      },
    }),
    headers: HEADERS,
  }
);
const runId = await response.json()["run_id"];
console.log(`Query run created with ID: ${runId}`);

const pollingInterval = 1 * 1000;
const start = Date.now();
const timeout = 20 * 60 * 1000; // 20min timeout
let runStatus = "";
const pollingFn = async () => {
  const statusResp = await fetch(
    `https://api.allium.so/api/v1/explorer/query-runs/${runId}/status`,
    {
      method: "GET",
      headers: HEADERS,
    }
  );
  runStatus = await statusResp.json();
  if (!["created", "queued", "running"].includes(runStatus)) {
    return;
  }
  console.log(`Current status: ${runStatus}. Waiting ${pollingInterval}s...`);
  if (Date.now() < start + timeout) {
    setTimeout(pollingFn, pollingInterval);
  }
};
pollingFn();

if (runStatus == "success") {
  const resultResponse = await fetch(
    `https://api.allium.so/api/v1/explorer/query-runs/${runId}/results?f=json`,
    {
      method: "GET",
      headers: HEADERS,
    }
  );
  const results = await resultResponse.json();
  console.log(
    `Query returned ${results["data"].length} rows, with fields: ${results[
      "meta"
    ]["columns"]
      .map((c) => c.get("name"))
      .join(", ")}`
  );
} else if (runStatus == "failed") {
  const errorResponse = await fetch(
    `https://api.allium.so/api/v1/explorer/query-runs/${runId}/error`,
    {
      method: "GET",
      headers: HEADERS,
    }
  );
  const errorMessage = await errorResponse.json();
  console.log(`Query failed with error: ${errorMessage}`
} else {
  console.log(`Query run finished with status: ${runStatus}. No results.`);
}

In a new terminal, run:

export API_KEY=<your api key>; export QUERY_ID=<your query id>;
curl -X 'POST' \
  "https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
  "parameters": {},
  "run_config": {
    "limit": 1000,
  }
}'

You will get back a run_id like { "run_id": "c7UViykJloFAUY2pwFjd" }.

In the same terminal, run:

export RUN_ID=<your run ID>;
curl -X 'GET' \
  "https://api.allium.so/api/v1/explorer/query-runs/{RUN_ID}/status" \
  -H 'accept: application/json' \
  -H "X-API-KEY: ${API_KEY}"

You will get back the current status of your query run. Keep polling to check for the status of your query run until it becomes success. If it becomes failed or canceled, your query run did not succeed and you will have to try again. Learn about statuses here. If your query failed, you can retrieve the error message by running:

curl -X 'GET' \
  "https://api.allium.so/api/v1/explorer/query-runs/${RUN_ID}/error" \
  -H 'accept: application/json' \
  -H "X-API-KEY: ${API_KEY}"

In the same terminal, run:

curl -X 'GET' \
  "https://api.allium.so/api/v1/explorer/query-runs/${RUN_ID}/results?f=json" \
  -H 'accept: application/json' \
  -H "X-API-KEY: ${API_KEY}"

and you will get your query run's 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 https://app.allium.so/explorer.
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 https://app.allium.so/explorer.
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)

In a typescript file, run:

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

const response = await fetch(`https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async`, {
  method: 'POST',
  body: json.dumps({
      "parameters": {},
      "run_config": {
          "limit": 1000,
      }
  }),
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': API_KEY,
  },
});

const data = await response.json();
console.log(data);

In a new terminal, run:

API_KEY=<your api key>; QUERY_ID=<your query id>; \
curl -X 'POST' \
  "https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
  "parameters": {},
  "run_config": {
    "limit": 1000,
  }
}'

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

In a typescript file, run:

...

const data = await response.json();
console.log(data);

const run_id = result["run_id"];

const status_response = await fetch(`https://api.allium.so/api/v1/explorer/query-runs/${run_id}/status`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': API_KEY,
  },
});

const run_status = await status_response.json();
console.log(run_status); // Possible values: created, queued, running, success, failed, canceled

In the same terminal, run:

curl -X 'GET' \
  'https://api.allium.so/api/v1/explorer/query-runs/{query_run_id}/status' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {api_key}'

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)

In a typescript file, run:

...

const run_status = await status_response.json();
console.log(run_status); // Possible values: created, queued, running, success, failed, canceled

if (run_status == "success") {
  const run_result_response = await fetch(`https://api.allium.so/api/v1/explorer/query-runs/${run_id}/results?f=json`, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': API_KEY,
    },
  });

  const run_result = await run_result_response.json();
  console.log(run_result);
}

In the same terminal, run:

curl -X 'GET' \
  'https://api.allium.so/api/v1/explorer/query-runs/{query_run_id}/results?f=json' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {api_key}'

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 !

Last updated 7 months ago