⚙️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

Name	Type	Description
api_key*	String

Request Body

Name	Type	Description
max_age	int	The maximum acceptable age for cached results. For the latest result, use 0

200: OK

403: Forbidden

404: Not Found

500: Internal Server Error

The Query URL is the URL for a particular query. In the example below, the URL is 1446.

Use 1446 as the <id> when accessing this query via API

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.

Response from initiating a query refresh

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.

Defining a parameter in the Query IDE

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.

{ 
    "parameters": {
    	"number_param": 100,
    	"date_param": "2020-01-01",
    	"date_range_param": {
    		"start": "2020-01-01",
    		"end": "2020-12-31"
    		}
    	},
      "max_age": 1800
    }
}

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.

Setting a refresh schedule on a query

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.

Results from a query refresh

• 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.