⚙️Execute A Query
Last updated
Last updated
Only [User] keys can start a query because queries as associated with the user.
In order to execute a query, call the following endpoint:
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.
api_key*
String
max_age
int
The maximum acceptable age for cached results. For the latest result, use 0
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.
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.
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.