POST/GET requests

Run your queries asynchronously

Introduction

The Explorer API allows you to

• Create a new query run for a query

• Retrieve the latest query run information for a query

• Retrieve the status of a query run

• Retrieve the results of a query run

• Cancel a query run

Create a new asynchronous query run

Execute Query Async

POST/api/v1/explorer/queries/{query_id}/run-async

Authorization

APIKeyBearer

Path parameters

query_id*Query Id

Body

application/json

parameters*Parameters

run_configRun Config

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/explorer/queries/{query_id}/run-async', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Request fields

Field name	Description
parameters	Key-value map of parameter names and their respective values.
run_config	Query run configuration to use when creating the query run.
run_config.limit	The query row limit to use for this query run.

Example

cURL

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: <YOUR API KEY>' \
  -d '{
  "parameters": {},
  "run_config": {
    "limit": 1000,
  }
}'

Python

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)

Typescript

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);

Retrieve the latest query run information for a query

Get Latest Query Run Handler

GET/api/v1/explorer/query-runs

Authorization

APIKeyBearer

Query parameters

Response

200422

Successful Response

Body

application/json

run_id*Run Id

query_id*Query Id

query_config*QueryConfig

creator_id*Creator Id

created_at*Created At

completed_atCompleted At

status*QueryRunStatus

An enumeration.

createdqueuedrunningsuccessfailedcanceled

statsQueryRunStats

errorError

resultsQueryRunResults

zed_tokenZed Token

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/explorer/query-runs?query_id=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

{
  "run_id": "text",
  "query_id": "text",
  "query_config": {
    "sql": "text",
    "limit": 0,
    "datastore_to_use": "snowflake"
  },
  "creator_id": "text",
  "created_at": "2024-12-21T11:55:57.857Z",
  "completed_at": "2024-12-21T11:55:57.857Z",
  "status": "created",
  "stats": {
    "start_time": "2024-12-21T11:55:57.857Z",
    "end_time": "2024-12-21T11:55:57.857Z",
    "datastore": "snowflake",
    "sql": "text",
    "row_count": 0,
    "data_size_bytes": 0
  },
  "error": "text",
  "results": {
    "storage_type": "gcs"
  },
  "zed_token": "text"
}

Retrieve the status of a query run

Get Query Run Status

GET/api/v1/explorer/query-runs/{run_id}/status

Authorization

APIKeyBearer

Path parameters

run_id*Run Id

Response

200422

Successful Response

Body

application/json

QueryRunStatus

An enumeration.

createdqueuedrunningsuccessfailedcanceled

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/explorer/query-runs/{run_id}/status', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

created

Possible query run statuses

Status	Description
created	Query has been created.
queued	Query has been queued for execution.
running	Query is currently executing.
success	Query has successfully executed.
failed	Query execution failed.
canceled	Query was canceled, likely due to user action.

Retrieve the results of a query run

Get Query Run Results

GET/api/v1/explorer/query-runs/{run_id}/results

Authorization

APIKeyBearer

Path parameters

run_id*Run Id

Query parameters

Response

200422

Successful Response

Body

application/json

sql*Sql

dataData

meta*QueryResultMeta

queried_atQueried At

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/explorer/query-runs/{run_id}/results', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

{
  "sql": "text",
  "meta": {
    "columns": [
      {
        "name": "text",
        "data_type": "text"
      }
    ]
  },
  "queried_at": "2024-12-21T11:55:57.857Z"
}

The query run result will have the following fields:

Field name	Description
sql	The SQL query executed in the request
data	The results of the query encoded as a list of JSON objects
meta	Metadata about the results.
meta.columns	List of the data's column names and types.
queried_at	The timestamp at which the query was executed

Cancel a query run

Cancel Query Run

POST/api/v1/explorer/query-runs/{run_id}/cancel

Authorization

APIKeyBearer

Path parameters

run_id*Run Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/explorer/query-runs/{run_id}/cancel', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}