⚙️Execute A Query
Only [User] keys can start a query because queries as associated with the user.
In order to execute a query, call the following endpoint:
Initiates a new query execution or returns a cached result
POST
https://query.nansen.ai/api/queries/<url>/refresh?api_key=<user_api_key>
The API prefers to return a cached result. If a cached result is not available then a new execution job begins and the job object is returned.
To bypass a stale cache, include a max_age
key which is an integer number of seconds. If the cached result is older than max_age
, the cache is ignored and a new execution begins. If you set max_age
to 0
this guarantees a new execution.
If passing parameters, they must be included in the JSON request body as a parameters
object.
Query Parameters
Request Body
The Query URL is the URL for a particular query. In the example below, the URL is 1446.
When the query has been initiated, you will see the following response. The job ID is what you need to check the status of the job.
Here’s an example JSON object including different parameter types to be included in the request body. The parameters are defined in the query editor and passed the query as a JSON format.
In this example, a parameter is defined with the keyword number_param
and type Number
in the Query editor. When accessing this query via API, include "number_param": 100
in the parameters section of the request.
Use of Cache
By default, a query will return the most recent cached result. To change this behavior, set max_age to 0. See below for more details.
Each query can have a refresh schedule, which will execute the query periodically to keep the data refresh. If the data needed is only every hour, you can set a refresh rate on the query to be 1 hour and retrieve the most recent result, without needing to trigger a refresh.
However, sometimes you want to trigger a new run of the query. This can be done by setting the max_age parameters, which will initatite a new query if the cached result is older than the configured seconds.
Setting max_age = 0 will always initiate a new query.
etting max_age = 5 will initiate a new query if the cached result is older than 5 seconds. It will return the cached result if the cached result is less than 5 seconds old.
Checking Job Status
Checks the status of the Query job
GET
https://query.nansen.ai/api/jobs/<job_id>?api_key=<user_api_key>
You may have to query the job status multiple times until it returns a success status.
The <job_id> comes from the previous step when a query refresh has been initiated.
GET: Returns a query task result (job)
Possible statuses:
1 == PENDING (waiting to be executed)
2 == STARTED (executing)
3 == SUCCESS
4 == FAILURE
5 == CANCELLED
When status is success, the job will include a
query_result_id
When the status shows success (3), a result id will be generated.
Last updated