Polling a Query Job

This endpoint lets you poll running Query Jobs.

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:

Description Request the current query status and results
MethodGET /api/v1/repositories/repo/queryjob/id
Request DataQueryInputJob
Response DataQueryResults
Authentication Requiredyes
Path ArgumentsDescriptionData typeRequired?
id ID of the query job stringrequired
repo Name of repository to be searched stringrequired
Return Codes
200 Request complete
400 Request is malformed and either missing critical fields or the JSON is badly structured
500 Request failed

When LogScale runs a search, it returns partial results, i.e. the results that were found at the time query was polled. LogScale searches the newest data first, and then searches progressively backward in time.

The effect is for LogScale to produces some results as soon as possible. If there are more results in the ouput, the done: true property in a poll query shows if the query is finished.

For example, to run a query for a query job matching ID {id}:

shell
$ curl https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$ID \
  -H "Authorization: Bearer $API_TOKEN"

The result may be quite large as it includes both the search results, and also the metadata about the query execution for those events found up until that point.

An example of this output is shown below, truncated for readability:

json
{
  "cancelled": false,
  "done": true,
  "events": [],
  "metaData": {
    "costs": {
      "liveCost": 0,
      "liveCostRate": 0,
      "staticCost": 0,
      "staticCostRate": 0
    },
    "digestFlow": {
      "ingestTimeKnownGood": 1686727519422,
      "maxIngestLatency": 0,
      "minIngestTimeIncluded": 1686727519422
    },
    "eventCount": 0,
    "extraData": {
      "hasMoreEvents": "false"
    },
    "filterQuery": {
      "allowEventSkipping": false,
      "end": 1688448692894,
      "includeDeletedEvents": false,
      "ingestEnd": 9223372036854775807,
      "ingestStart": 0,
      "isAlertQuery": false,
      "isInteractive": false,
      "isLive": false,
      "isRepeatingSubquery": false,
      "languageVersion": "legacy",
      "noResultUntilDone": false,
      "queryString": "*",
      "showQueryEventDistribution": false,
      "start": 1688362292894,
      "useIngestTime": false
    },
    "isAggregate": false,
    "pollAfter": 300,
    "processedBytes": 0,
    "processedEvents": 0,
    "queryEnd": 1688448692894,
    "querySpent": {
      "day": {
        "liveCost": 0,
        "queryCount": 1,
        "staticCost": 0
      },
      "hour": {
        "liveCost": 0,
        "queryCount": 1,
        "staticCost": 0
      },
      "oneMinute": {
        "liveCost": 0,
        "queryCount": 1,
        "staticCost": 0
      },
      "tenMinutes": {
        "liveCost": 0,
        "queryCount": 1,
        "staticCost": 0
      }
    },
    "queryStart": 1688362292894,
    "quotaTotalSpent": {
      "day": {
        "liveCost": 0,
        "queryCount": 2,
        "staticCost": 0
      },
      "hour": {
        "liveCost": 0,
        "queryCount": 2,
        "staticCost": 0
      },
      "oneMinute": {
        "liveCost": 0,
        "queryCount": 0,
        "staticCost": 0
      },
      "tenMinutes": {
        "liveCost": 0,
        "queryCount": 2,
        "staticCost": 0
      }
    },
    "responderVHost": 2,
    "resultBufferSize": 0,
    "timeMillis": 3,
    "totalWork": 0,
    "warnings": [],
    "workDone": 0
  },
  "queryEventDistribution": {
    "events": [
      {
        "_bucket": "1688362200000",
        "_count": "0"
      },
      {
        "_bucket": "1688363100000",
        "_count": "0"
      },
...
      {
        "_bucket": "1688448600000",
        "_count": "0"
      }
    ],
    "extraData": {
      "bucket_first_bucket": "1688362200000",
      "bucket_last_bucket": "1688448600000",
      "bucket_span_humanized": "15m",
      "bucket_span_millis": "900000"
    }
  },
  "warnings": []
}

The response is a formatted as a JSON object with the following top-level elements:

Table:

FieldTypeDescription
cancelledboolean Indicates whether the query has been cancelled.
doneboolean True if the query has run to completion
eventsarray JSON of the events as an array
filterMatchesarray Entries that match the supplied filter
metaData  Metadata about the result set in the form of QueryMetaDataJson
queryEventDistribution  Information used to render the distrubtion graph. Only supplied when the showQueryEventDistribution is set to true.
warningsarray List of warnings returned using the WarningJson.

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.

Important

Query timeouts are in operation for query jobs. If you do not poll a query for 30 seconds, then it stops and deletes itself. Live queries keep running for an hour without being polled.