Quickstart
A quick introduction to using the Explorer API
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:
1
SELECT * FROM ethereum.raw.blocks LIMIT 100
- Have a local environment set up where you can run
cURL,pythonorjscode.
Python
Typescript
cURL
run_query_async.py
1
import time, requests
2
3
QUERY_ID = "<your query ID>"
4
API_KEY = "<your api key here>"
5
6
response = requests.post(
7
f"https://api.allium.so/api/v1/explorer/queries/{QUERY_ID}/run-async",
8
json={"parameters": {}, "run_config": {"limit": 1000}},
9
headers={"X-API-Key": API_KEY},
10
timeout=10,
11
)
12
# If you get an error, print out response.json() to learn more.
13
run_id = response.json()["run_id"]
14
print(f"Query run created with ID: {run_id}")
15
16
polling_interval, start, timeout = 1, time.time(), 20 * 60 # 20min timeout
17
while time.time() < start + timeout:
18
response = requests.get(
19
f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/status",
20
headers={"X-API-Key": API_KEY},
21
timeout=10,
22
)
23
run_status = response.json()
24
if run_status not in ["created", "queued", "running"]:
25
break
26
print(f"Current status: {run_status}. Waiting {polling_interval}s...")
27
time.sleep(polling_interval)
28
29
if run_status == "success":
30
response = requests.get(
31
f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/results?f=json",
32
headers={"X-API-Key": API_KEY},
33
)
34
results = response.json()
35
print(
36
f"Query returned {len(results['data'])} rows, with "
37
f"fields: {', '.join(column.get('name') for column in results['meta']['columns'])}"
38
)
39
elif run_status == "failed":
40
response = requests.get(
41
f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/error",
42
headers={"X-API-Key": API_KEY},
43
)
44
error_message = response.json()
45
print(
46
f"Query failed with error: {error_message}"
47
)
48
else:
49
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.`);
}
- 1.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" }.- 2.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}"
- 3.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())
With our API, you can easily query Allium's data and retrieve results using simple HTTP requests. To get started, follow these steps:
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.
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.
You will also need your query ID in order to identify the query you wish to run.
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.
Now we want to run your query asynchronously.
Python
Typescript
cURL
In a python script, run:
1
import requests
2
3
QUERY_ID = "<your query ID here>"
4
API_KEY = "<your api key here>"
5
6
response = requests.post(
7
f"https://api.allium.so/api/v1/explorer/queries/{QUERY_ID}/run-async",
8
json={
9
"parameters": {},
10
"run_config": {
11
"limit": 1000,
12
}
13
},
14
headers={
15
"X-API-Key": API_KEY
16
},
17
)
18
19
result = response.json()
20
print(result)
In a typescript file, run:
1
const QUERY_ID = "<your query ID here>"
2
const API_KEY = "<your api key here>"
3
4
const response = await fetch(`https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async`, {
5
method: 'POST',
6
body: json.dumps({
7
"parameters": {},
8
"run_config": {
9
"limit": 1000,
10
}
11
}),
12
headers: {
13
'Content-Type': 'application/json',
14
'X-API-KEY': API_KEY,
15
},
16
});
17
18
const data = await response.json();
19
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.
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:
Python
Typescript
cURL
Continuing from the previous script:
1
...
2
3
result = response.json()
4
print(result)
5
6
run_id = result["run_id"]
7
8
response = requests.get(
9
f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/status",
10
headers={
11
"X-API-Key": API_KEY
12
},
13
)
14
15
run_status = response.json()
16
print(run_status) # Possible values: created, queued, running, success, failed, canceled
In a typescript file, run:
1
...
2
3
const data = await response.json();
4
console.log(data);
5
6
const run_id = result["run_id"];
7
8
const status_response = await fetch(`https://api.allium.so/api/v1/explorer/query-runs/${run_id}/status`, {
9
method: 'GET',
10
headers: {
11
'Content-Type': 'application/json',
12
'X-API-KEY': API_KEY,
13
},
14
});
15
16
const run_status = await status_response.json();
17
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.
Finally, we want to retrieve the results of the query run. To do so:
Python
Typescript
cURL
Continuing from the previous script:
1
...
2
3
run_status = response.json()
4
print(run_status) # Possible values: created, queued, running, success, failed, canceled
5
6
if run_status == "success":
7
response = requests.get(
8
f"https://api.allium.so/api/v1/explorer/query-runs/{run_id}/results?f=json",
9
headers={
10
"X-API-Key": API_KEY
11
},
12
)
13
14
run_results = response.json()
15
print(run_results)
In a typescript file, run:
1
...
2
3
const run_status = await status_response.json();
4
console.log(run_status); // Possible values: created, queued, running, success, failed, canceled
5
6
if (run_status == "success") {
7
const run_result_response = await fetch(`https://api.allium.so/api/v1/explorer/query-runs/${run_id}/results?f=json`, {
8
method: 'GET',
9
headers: {
10
'Content-Type': 'application/json',
11
'X-API-KEY': API_KEY,
12
},
13
});
14
15
const run_result = await run_result_response.json();
16
console.log(run_result);
17
}
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!
Last modified 4d ago