GET Saved Query

GET Query


Request used to Query your Log entries using a Saved Query.

URL

https://REGION.rest.logs.insight.rapid7.com/query/saved_query/:saved_query_id/

REGION is the data center where your account is - e.g. "us" or "eu"

Method:

GET

Authentication:

Read Only key or above is required. See: REST API Authentication

URL Params

ParamAboutRequiredExample
saved_query_idSaved Query IDTrue/saved_query/f9c6e2c1-ac7a-4a29-8faa-a8d70f96df71/
fromlower bound of the time range you want to query against; UNIX timestamp in millisecondsFalsefrom=1450557604000
tolower bound of the time range you want to query against; UNIX timestamp in millisecondsFalseto=1460557604000
per_pagenumber of log entries to return per page. Default of 50Falseper_page=50
sequence_numberthe earlier sequence number of a log entry to start searching fromFalsesequence_number=10

Note that if you are already suing a from and to value in your Saved Query then they are not required for performing a GET request.

Success Response:

Code: 200 for a successful queryContent:

json
1
{
2
"logs": ["f9c6e2c1-ac7a-4a29-8faa-a8d70f96df70"],
3
"statistics": {...},
4
"leql": {
5
"statement": "where(something) calculate(count)",
6
"during": {
7
"from": 1,
8
"to": 10000
9
}
10
}
11
}

Code: 202 for a query that successfully started but has not yet finishedContent:

json
1
{
2
"logs": [
3
"f9c6e2c1-ac7a-4a29-8faa-a8d70f96df70"
4
],
5
"id": "deace1fd-e605-41cd-a45c-5bf1ff0c3402-1",
6
"progress":0,
7
"query": {
8
"statement": "where(foo) calculate(count:x)",
9
"during": {
10
"to": 100000,
11
"from": 100
12
}
13
},
14
"links": [{
15
"rel": "self",
16
"href": "https://us.rest.logs.insight.rapid7.com/query/deace1fd-e605-41cd-a45c-5bf1ff0c3402-1"
17
}]
18
}

Sample Code

python
1
import requests
2
import json
3
import time
4
5
def continue_request(req):
6
if 'links' in req.json():
7
continue_url = req.json()['links'][0]['href']
8
new_response = make_request(continue_url)
9
handle_response(new_response)
10
11
12
def handle_response(resp):
13
response = resp
14
print response.status_code
15
if response.status_code == 200:
16
print json.dumps(resp.json(), indent=4)
17
return
18
if response.status_code == 202:
19
continue_request(resp)
20
return
21
if response.status_code > 202:
22
print 'Error status code ' + str(response.status_code)
23
return
24
25
26
def make_request(provided_url=None):
27
headers = {'x-api-key': '5b971ffa-639a-4888-b3b3-5493dbb4f50c'}
28
29
url = "https://us.rest.logs.insight.rapid7.com/query/saved_query/be670957-d401-440d-b3ac-06ee0aab7cea"
30
if provided_url:
31
url = provided_url
32
req = requests.get(url, headers=headers)
33
return req
34
35
36
def print_query():
37
req = make_request()
38
handle_response(req)
39
40
def start():
41
print_query()
42
43
44
if __name__ == '__main__':
45
start()

Long-running queries:

Depending on the size of the underlying dataset of the complexity of the query, a request may not yield a value straight away. In this case a well-formed query will return an HTTP 202 response and an ID you can use to check its state.

An example response would look like this:

1
{
2
"logs": [
3
"f9c6e2c1-ac7a-4a29-8faa-a8d70f96df70"
4
],
5
"id": "deace1fd-e605-41cd-a45c-5bf1ff0c3402-1",
6
"progress":0,
7
"query": {
8
"statement": "where(foo) calculate(count:x)",
9
"during": {
10
"to": 100000,
11
"from": 100
12
}
13
},
14
"links": [{
15
"rel": "self",
16
"href": "https://us.rest.logs.insight.rapid7.com/query/deace1fd-e605-41cd-a45c-5bf1ff0c3402-1"
17
}]
18
}

You can poll this query for a value by issuing a GET request with the link returned in the response, e.g. curl https://us.rest.logs.insight.rapid7.com/query/deace1fd-e605-41cd-a45c-5bf1ff0c3402-1 -H 'x-api-key: 00112233-4455-6677-8899-aabbccddeeff '.

The endpoint /query/ will give one of the following responses:

  • A HTTP 200 status and a response containing a value (list of events or statistical results as above) if the query completed
  • A HTTP 202 status and a response containing an ID and links to continue polling if the query is still in progress. The response will look like this:
1
{
2
"id": "deace1fd-e605-41cd-a45c-5bf1ff0c3402-0",
3
"links": [{
4
"rel": "self",
5
"href": "https://us.rest.logs.insight.rapid7.com/query/deace1fd-e605-41cd-a45c-5bf1ff0c3402-0"
6
}]
7
}

There is no limit on how frequently you can poll a query, or how many times you may poll it. However, if you do not poll a query resource for 20 seconds, it will expire. Subsequent calls to that resource will return a 404.

Error Response:

  • Code: 400 for bad user input

  • Code: 404 for a resource that was badly formed or log could not be found or a Saved Query which has no logs specified.

  • Code: 500 for any internal error, for example if the query could not be executed