Logs API

Authentication

Authentication is done via basic auth with your API token. Get your token by clicking "New API Token" on the page: https://app.runreveal.com/dash/workspace/api-tokens.

e.g. with cURL, set the authorization header like so:

$ curl -H 'Authorization: Basic <token>' https://api.runreveal.com/...

Logs Query Endpoint

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

The query endpoint accepts SQL queries and returns results. The token is scoped to a single workspace, so no workspaceid parameter is required.

By default the query runs synchronously and returns up to limit results inline (default 50, max 100000). The request body accepts:

query — the SQL to run.
source — a free-form label for where the query originated (e.g. api).
parameters — substitution values for the query. The from, to, window, and interval parameters control the time range and default to the last 24 hours if omitted.
limit — maximum rows returned in this response.
async — set to true to queue the query and return immediately with a queryID (requires the async-queries feature). Poll the results endpoint for completion.

Here's a full example using cURL:

curl 'https://api.runreveal.com/logs/query/v3' \
  -H 'authorization: Basic <token>' \
  -H 'content-type: application/json' \
  --data-raw '{"query":"SELECT receivedAt, workspaceID, sourceType, id, eventName FROM logs LIMIT 2;","source":"api","parameters":{},"limit":1000}'
{
  "success": true,
  "result": {
    "queryID": "2e2GQkLQiZNUyDIZXnvGHssbRIH",
    "status": "completed",
    "query": "SELECT receivedAt, workspaceID, sourceType, id, eventName FROM logs LIMIT 2;",
    "parameters": {},
    "error": "",
    "resultCount": 2,
    "totalRows": 2,
    "totalResults": 2,
    "createdAt": "2024-03-22T08:14:05.958701794Z",
    "startedAt": "2024-03-22T08:14:05.958701794Z",
    "completedAt": "2024-03-22T08:14:05.997538321Z",
    "runTime": "38.836527ms",
    "runTimeMs": 38,
    "source": "api",
    "limit": 1000,
    "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"
      ]
    ]
  }
}

Use the results endpoint to page through a completed query's results, or to poll an asynchronous query for completion. Pass limit and offset to page. The queryID is returned by the query endpoint above.

If the query has not yet completed, totalRows (and the legacy totalResults) will be -1.

curl 'https://api.runreveal.com/logs/query/v3/results' \
  -H 'authorization: Basic <token>' \
  -H 'content-type: application/json' \
  --data-raw '{"queryID":"2e2GQkLQiZNUyDIZXnvGHssbRIH","limit":50,"offset":0}'
{
  "success": true,
  "result": {
    "queryID": "2e2GQkLQiZNUyDIZXnvGHssbRIH",
    "status": "completed",
    "query": "SELECT receivedAt, workspaceID, sourceType, id, eventName FROM logs LIMIT 2;",
    "parameters": {},
    "error": "",
    "resultCount": 2,
    "totalRows": 2,
    "totalResults": 2,
    "createdAt": "2024-03-22T08:14:05.958702Z",
    "startedAt": "2024-03-22T08:14:05.958702Z",
    "completedAt": "2024-03-22T08:14:05.997538Z",
    "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. Cancellation is shared across query versions — use it for queries started via the v3 endpoint too.

curl 'https://api.runreveal.com/logs/query/v2/cancel?queryID=<queryID>' \
  -H 'authorization: Basic <token>'
{
  "success": true
}

Logs API

Authentication

Logs Query Endpoint

Results Endpoint

Cancellation Endpoint

On this page