Using the REST API v2 Datasearch Endpoint

Overview

Here are the API specifications that must be adhered to when making HTTP calls. The Datasearch APIs are based on the Skope IT Query Language.

Request Parameters

HTTP Method: GET

URL Parameter	Description	Example
query	Advanced filter for retrieving events.	query=access_method+eq+’value’+and+category+like+’abc’
fields	Names of the columns whose values want to be retrieved in results.	fields=app,category
starttime	Unix timestamp of start time of events in seconds.	starttime=1641860455
endtime	Unix timestamp of end time of events in seconds.	endtime=1641866455
timeout	Query timeout, in seconds. Default: 180	timeout=180
offset	Number of rows to skip before presenting the results.	offset=1
limit	Max number of records to return in the result.	limit=20
sublimit	Max number of records to limit the sub-aggregation by.	sublimit=10
groupbys	Fields to aggregate on.	groupbys=category,app
subgroupbys	Secondary fields to aggregate on.	subgroupbys=category
orderbys	Fields to sort the events by either ascending or descending order.	orderbys=access_method+asc,app+desc

 

Response Body

Success Response

If status.execution == “SUCCESS”, then the request is successful. Check the result for the actual returned data.

# JSON
{
  "result": [], # slice of json results
  "status": {
    "execution": "SUCCESS",
    "count": 1, # length of results
    "message": "Executed Successfully",
    "status_code": 200
  }
}

Error Response

If status.execution == “FAILED”, then the request failed. Check for the error message.

# JSON
{
  "result": [], # slice of json results
  "status": {
    "execution": "FAILED",
    "count": 1, # length of results
    "message": "Executed Unsuccessfully",
    "status_code": non-200 code
  }
}

Query Examples

Since the Datasearch endpoints are intended for ad-hoc query purposes, and allows you to retrieve events in the system by providing various parameters in the request, you can use this endpoint to filter and retrieve all and/or specific events based on criteria like ID, time range, and other metadata. Here are a couple of examples:

• You can apply an aggregation to filter alert events and present the total count of alerts over a designated timeframe.
  Query

  /api/v2/events/datasearch/alert?starttime=1731535136&endtime=1736805536&fields=count_total:count(id)

  Response

  {
     "result":[
        {
           "count_total":372359
        }
     ],
     "status":{
        "count":1,
        "execution":"SUCCESS",
        "message":"Executed Successfully",
        "status_code":200
     }
  }

• You can also combine various operations to display aggregated metrics over a time period.
  Query

  /api/v2/events/datasearch/page?starttime=0&endtime=0&groupby=user&sortby=server_bytes&fields=sessions=sum(session_number_unique),server_bytes=sum(server_bytes_total),client_bytes=sum(client_bytes_total),numbytes=sum(numbytes_total)

  Response

  {
     "result":[
        {
           "client_bytes":7167685749707,
           "numbytes":7183668827587,
           "server_bytes":14567122273,
           "sessions":9044400340052308025
        }
     ],
     "status":{
        "count":1,
        "execution":"SUCCESS",
        "message":"Executed Successfully",
        "status_code":200
     }
  }