Falcon LogScale Documentation

With absolute time, you specify a number that expresses the precise time in milliseconds since the Unix epoch (Unix time) in the UTC/Zulu time zone. This method is shown in the following example:

{
  "queryString": "",
  "start": 1473449370018,
  "end": 1473535816755
}

With relative time, you specify the start and end time as a relative time such as 1minute or 24hours. LogScale supports this using relative time modifiers. LogScale treats the start and end times as relative times if you specify them as strings.

When providing a timestamp, relative time modifiers are specified relative to "now".

See the Relative Time Syntax reference page.

This method is shown in the following examples:

Search the last 24 hours:

{
  "queryString": "ERROR",
  "start": "24hours",
  "end": "now"
}

You can also mix relative and absolute time modifiers. For example, to search from a specified moment in time until two days ago:

{
  "queryString": "loglevel=ERROR",
  "start": 1473449370018,
  "end": "2days"
}

LogScale returns data in different formats depending on the media type you set in the ACCEPT header of the HTTP request.

Data can be returned in the following formats:

In these examples, $YOUR_LOGSCALE_URL is the URL for your Humio Cloud Account.

This live query returns an empty search, finding all events in a time window going 10 seconds back in time.

Notice the ACCEPT header. This tells the server to stream data as Newline Delimited JSON.

curl https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/query \
  -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Accept: application/x-ndjson" \
  -d '{"queryString":"","start":"10s","isLive":true}'

This query groups results by service and counts the number of events for each service. The query blocks until it is complete and returns events as a JSON array:

curl https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/query \
  -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Accept: application/json" \
  -d '{"queryString":"count()","start": "1h","end":"now","isLive":false}'

The Query Jobs endpoint lets you run a query and check its status later.

To execute a query using the Query Jobs endpoint, you first have to start it, and then subsequently poll its current status in a separate request.

The Query Jobs endpoint is designed to support the web front end. This means that filter queries only return a maximum of 200 matching events and aggregate queries up to a maximum of 1500 rows. The API has facilities to support Web UIs of the Query Jobs poll endpoint).

To start a Query Job, POST the query to:

POST /api/v1/repositories/$REPOSITORY_NAME/queryjobs

The request body is similar to the in the query endpoint.

Starting a query yields a response of the form:

HTTP/1.1 200 OK
{ id: "some-long-id" }

The id field indicates the $ID for the query, which you can then poll using the HTTP GET method (see Poll).

To poll a running Query Job, make an HTTP GET request to the job.

In the following example request, replace $ID with the ID from the response of the Query Jobs:

GET /api/v1/repositories/$REPOSITORY_NAME/queryjobs/$ID

When LogScale runs a search, it returns partial results. It returns the results that it found at the time of the polling. LogScale searches the newest data first, and then searches progressively backward in time.

This way, LogScale produces some results right away. The done: true property in a poll query shows if the query is finished.

The response is a JSON object with the following attributes:

The MetaData field contains the number of matching events, the query boundary, and information about the attributes and their unique value domains in the response. It also contains the list of warnings generated by the query.

To stop a Query Job, you can issue a DELETE request to the URL of the Query Job:

DELETE /api/v1/repositories/$REPOSITORY_NAME/queryjobs/$ID

Standard HTTP response codes