Reference
Logs API

Logs API

Authentication

Authentication is done via basic auth with the user portion set to an empty string. Get your token by clicking "New API Token" on the page: https://runreveal.com/dash/account (opens in a new tab) .

e.g. with cURL, set the -u flag with the API token in the password field like so:

$ curl -u ':<token>' https://api.runreveal.com/...

The authorization header is the base64 encoding of that string (:<token>) with no newline appended to the end, with Basic as a leading indicator for the auth type in the header like so:

authorization: Basic <base64 encoded token>

e.g. (-n removes the newline from echo)

auth=$(echo -n ':<token>' | base64) ; echo "authorization: Basic $auth"

Logs Query Endpoint

https://api.runreveal.com/logs/query/v2

The first endpoint is the query endpoint where you can submit queries of any format. Currently the supported formats are: pql, sql, or natural language. Set the useAI and usePQL flags to query using natural language and PQL, respectively. The arguments are mutually exclusive, and setting both is invalid but if useAI is set, it will take precedence. The query will be converted into the corresponding SQL before being submitted to the database backend.

This endpoint will kick off the query and return up to limit results. The query will continue running in the background.

Here's a full example using cURL:

curl 'https://api.runreveal.com/logs/query/v2?workspaceid=<wkspID>' \
  -H 'authorization: Basic <b64-token>' \
  -H 'content-type: application/json' \
  --data-raw '{"query":"SELECT receivedAt, workspaceID, sourceType, id, eventName FROM runreveal.logs LIMIT 2;","useAI":false,"usePQL":false,"source":"ui-query","parameters":{"a":"b"},"limit":1000}'
{
  "success": true,
  "result": {
    "queryID": "2e2GQkLQiZNUyDIZXnvGHssbRIH",
    "canceled": false,
    "query": "SELECT receivedAt, workspaceID, sourceType, id, eventName FROM runreveal.logs LIMIT 2;",
    "aiText": "",
    "pqlText": "",
    "parameters": {
      "a": "b"
    },
    "error": "",
    "resultCount": 2,
    "totalResults": 2,
    "startedAt": "2024-03-22T08:14:05.958701794Z",
    "runTime": "38.836527ms",
    "runTimeMs": 38,
    "limit": 0,
    "offset": 0,
    "columns": [
      "receivedAt",
      "workspaceID",
      "sourceType",
      "id",
      "eventName"
    ],
    "columnTypes": [
      "DateTime",
      "String",
      "LowCardinality(String)",
      "String",
      "String"
    ],
    "rows": [
      [
        "2024-02-08T23:18:45Z",
        "<wkspID>",
        "gcplogs",
        "2c6a8tdYFRWa7oqVudOrGTIP3B7",
        "google.identity.oauth2.GetTokenInfo"
      ],
      [
        "2024-02-08T23:18:55Z",
        "<wkspID>",
        "gcplogs",
        "2c6aA74bB5VCJVesecPRD9cv2ul",
        "google.identity.oauth2.GetTokenInfo"
      ]
    ]
  }
}

Results Endpoint

If the query has completed, you can query it using the results endpoint. You can pass in a limit and offset parameter to page through the results. The queryID is used to load the results, and is returned upon querying using the above endpoint.

If the query has not yet completed, totalResults will be -1.

curl 'https://api.runreveal.com/logs/query/v2/results?workspaceid=<wkspID>' \
  -H 'authorization: Basic <b64-token>' \
  -H 'content-type: application/json' \
  --data-raw '{"queryID":"2e2GQkLQiZNUyDIZXnvGHssbRIH","limit":50,"offset":0}'
{
  "success": true,
  "result": {
    "queryID": "2e2GQkLQiZNUyDIZXnvGHssbRIH",
    "canceled": false,
    "query": "SELECT receivedAt, workspaceID, sourceType, id, eventName FROM runreveal.logs LIMIT 2;",
    "aiText": "",
    "pqlText": "",
    "parameters": {
      "a": "b"
    },
    "error": "",
    "resultCount": 2,
    "totalResults": 2,
    "startedAt": "2024-03-22T08:14:05.958702Z",
    "runTime": "38.836527ms",
    "runTimeMs": 38,
    "limit": 50,
    "offset": 0,
    "columns": [
      "receivedAt",
      "workspaceID",
      "sourceType",
      "id",
      "eventName"
    ],
    "columnTypes": [
      "DateTime",
      "String",
      "LowCardinality(String)",
      "String",
      "String"
    ],
    "rows": [
      [
        "2024-02-08T23:18:45Z",
        "2KUOdhvRReF5RZfQX8ILneT4fSd",
        "gcplogs",
        "2c6a8tdYFRWa7oqVudOrGTIP3B7",
        "google.identity.oauth2.GetTokenInfo"
      ],
      [
        "2024-02-08T23:18:55Z",
        "2KUOdhvRReF5RZfQX8ILneT4fSd",
        "gcplogs",
        "2c6aA74bB5VCJVesecPRD9cv2ul",
        "google.identity.oauth2.GetTokenInfo"
      ]
    ]
  }
}

Cancellation Endpoint

This cancels an inflight query given by the queryID.

curl 'https://api.runreveal.com/logs/query/v2/cancel?workspaceid=<wkspID>&queryID=<queryID>' \
  -H 'authorization: Basic <b64-token>'
{
  "success": true
}
Detection as CodeRelease Notes