API for Logs

To interact programmatically with logs, you must issue the required query requests.

The query is embedded within the GraphQL request arguments. Kloudfuse works with tables, so the result of the query is often a table that follows a schema defined by the column headers.

Embed the supported query within the graphQL request arguments. See instructions on how to use GraphQL.

For authorization, see Authorization for API calls.

Supported queries

getFacetValueCountsStream: Get count facet values for the specified time range, with filter support.
getLabelValuesStream: Get label values for the specified label name.
getLogMetricsTimeSeries: Get a time series of metrics derived from logs for a given time range with filter support using the LogQL query engine.
getLogMetricsTimeSeriesStream: Get a time series of metrics derived from logs for the specified time range using the LogQL query engine.
getLogsV2Stream: Get logs based on time and log filters, with sorting and limit support.

For additional log APIs, implemented for FuseQL search, see FuseQL API for Logs.

Prerequisites

Configure a GraphQL client. See GraphQL documentation.
Authenticate using the basic HTTP authentication protocol.

getFacetValueCountsStream

Get count facet values for the specified time range, with filter support.

Syntax

subscription { (1)
  getFacetValueCountsStream(
    facetName: String! (2)
    dataType: String (3)
    logQuery: LogQuery (4)
    timestamp: Time (5)
    durationSecs: Int (6)
    limit: Int (7)
    timeoutSecs: Int (8)
    options: String (9)
  ): [ValueCount]! (10)
}

1	`subscription`: This is a subscription; calls return multiple responses.
2	`facetName`: The name of the facet queried.
3	`dataType`: Datatype of facet; defaults to `String`.
4	`logQuery`: Query of logs, including all operators, *except* Window and Aggregation.
5	`timestamp`: Beginning of the sampled time frame.
6	`durationSecs`: Going back duration in seconds; defaults to 300 seconds.
7	`limit`: Limit the number of results; defaults to 1000.
8	`timeoutSecs`: Optional query timeout, in seconds; default is 60 seconds.
9	`options`: Query options; string of comma-separated `k=v` key-value pairs. Not implemented — DO NOT USE.
10	`ValueCount`: The count of logs that match the specified criteria, including the following: `value` (Value of the label or facet) `floatValue` (FloatValue of the label or facet) `count` (Count of value based on entityQuery, logQuery and time range)

Examples

Initial query

getFacetValueCountsStream(
        durationSecs: 300
        facetName: "@:STRING.requestID"
        logQuery: {and: [{ and: [{ eq: { facetName: "level", value: "info" } }{ eq: { facetName: "source", value: "apigateway" } }] }]},
        limit: 500,
        timestamp: "2025-04-08T12:17:13-07:00",
      ) {
        count
        floatValue
        value
      }
    }

getLabelValuesStream

Get label values for the specified label name.

Syntax

subscription { (1)
  getLabelValuesStream(
  labelName: String! (2)
  logQuery: LogQuery (3)
  timestamp: Time (4)
  durationSecs: Int (5)
  includeCount: Boolean (6)
  limit: Int (7)
  contains: String (8)
  timeoutSecs: Int (9)
  options: String (10)
): [ValueCount]! (11)

1	`subscription`: This is a subscription; calls return multiple responses.
2	`labelName`: The name of the label queried.
3	`logQuery`: Query of logs, including all operators, *except* Window and Aggregation.
4	`timestamp`: Beginning of the sampled time frame.
5	`durationSecs`: Going back duration in seconds; defaults to 300 seconds.
6	`includeCount`: Whether to include count of values in result (`True` of `False`).
7	`limit`: Limit the number of results; defaults to 1000.
8	`contains`: Filter label values that contain the specified string.
9	`timeoutSecs`: Optional query timeout, in seconds; default is 60 seconds.
10	`options`: Query options; string of comma-separated `k=v` key-value pairs. Not implemented — DO NOT USE.
11	`ValueCount`: The count of logs that match the specified criteria, including the following: `value` (Value of the label or facet) `floatValue` (FloatValue of the label or facet) `count` (Count of value based on entityQuery, logQuery and time range)

Examples

Initial query

subscription {
  getLabelValuesStream(
        durationSecs: 300
        includeCount: true
        labelName: "source"
        logQuery: {and: [{ and: [{ eq: { facetName: "level", value: "info" } }{ eq: { facetName: "source", value: "apigateway" } }] }]},
        limit: 1000,
        timestamp: "2025-04-08T12:17:13-07:00",
  ) {
        count
        value
      }
}

getLogMetricsTimeSeries

Get a time series of metrics derived from logs for a given time range with filter support using the LogQL query engine.

Syntax

{ (1)
  getLogMetricsTimeSeries(
    logQuery: LogQuery  (2)
    timestamp: Time (3)
    durationMs: Int (4)
    stepMs: Int! (5)
    lookBackMs: Int! (6)
    facetName: String (7)
    facetNormalizeFunction: NormalizeFunction (8)
    rangeAggregate: String! (9)
    rangeAggregateParam: Float (10)
    rangeAggregateGrouping: Grouping (11)
    vectorAggregate: String (12)
    vectorAggregateParam: Float (13)
    vectorAggregateGrouping: Grouping (14)
    logQL: String (15)
    timeoutSecs: Int (16)
    options: String (17)
  ): [TimeSeries] (18)
}

1	This is a query; calls return a single response.
2	`logQuery`: Query of logs, including all operators, *except* Window and Aggregation.
3	`timestamp`: Beginning of the sampled time frame.
4	`durationMs`: The length of the sampled time, in milliseconds.
5	`stepMs`: The query resolution that determines the interval between data points in a chart, in milliseconds.
6	`lookBackMs`: Specifies how far back in time to search for data points when evaluating a query, influencing the data used for each step, in milliseconds.
7	`facetName`: The name of the facet queried.
8	`facetNormalizeFunction`: The function to apply to the facet value, to normalize to a time duration or data size (in bytes).
9	`rangeAggregate`: Either an inner or time range aggregate, such as `rate` or any `*_over_time` aggregate.
10	`rangeAggregateParam`: The parameter for the range aggregate function, such as `quantile_over_time(0.99, {source=foo} \| unwrap request_time [1m])`.
11	`rangeAggregateGrouping`: The grouping for the log range aggregate.
12	`vectorAggregate`: The vector aggregate, such as `sum`, `min`, `max`, `avg`, `std_dev`, `std_var`, and so on.
13	`vectorAggregateParam`: The parameter for the vector aggregate function, such as `topk(10, count_over_time({source=foo} [1m])`.
14	`vectorAggregateGrouping`: The grouping for the vector aggregate.
15	`logQL`: Optional query timeout argumet, in seconds; default is 60 seconds.
16	`timeoutSecs`: Optional query timeout, in seconds; default is 60 seconds.
17	`options`: Query options; string of comma-separated `k=v` key-value pairs. Not implemented — DO NOT USE.
18	`TimeSeries`: The returned time series data, including the following: `points` (Individual datapoints, constructed from a timestamp and float value) `tags` (Map)

Examples

Initial request

{
  getLogMetricsTimeSeries(
    durationMs: 300000
    logQL: "sum(count_over_time({ source=~\".+\" }    [5s]))"
    stepMs: 5000
    timestamp: "2025-04-09T12:26:15-07:00"
  ) {
    points {
      ts
      value
    }
    tags
  }
}

getLogMetricsTimeSeriesStream

Get a time series of metrics derived from logs for the specified time range using the LogQL query engine.

Syntax

subscription { (1)
  getLogMetricsTimeSeriesStream(
    logQuery: LogQuery  (2)
    timestamp: Time (3)
    durationMs: Int (4)
    stepMs: Int! (5)
    lookBackMs: Int! (6)
    facetName: String (7)
    facetNormalizeFunction: NormalizeFunction (8)
    rangeAggregate: String! (9)
    rangeAggregateParam: Float (10)
    rangeAggregateGrouping: Grouping (11)
    vectorAggregate: String (12)
    vectorAggregateParam: Float (13)
    vectorAggregateGrouping: Grouping (14)
  ): [TimeSeries] (15)
}

1	`subscription`: This is a subscription; calls return multiple responses.
2	`logQuery`: Query of logs, including all operators, *except* Window and Aggregation.
3	`timestamp`: Beginning of the sampled time frame.
4	`durationMs`: The length of the sampled time, in milliseconds.
5	`stepMs`: The query resolution that determines the interval between data points in a chart, in milliseconds.
6	`lookBackMs`: Specifies how far back in time to search for data points when evaluating a query, influencing the data used for each step, in milliseconds.
7	`facetName`: The name of the facet queried.
8	`facetNormalizeFunction`: The function to apply to the facet value, to normalize to a time duration or data size (in bytes).
9	`rangeAggregate`: Either an inner or time range aggregate, such as `rate` or any `*_over_time` aggregate.
10	`rangeAggregateParam`: The parameter for the range aggregate function, such as `quantile_over_time(0.99, {source=foo} \| unwrap request_time [1m])`.
11	`rangeAggregateGrouping`: The grouping for the log range aggregate.
12	`vectorAggregate`: The vector aggregate, such as `sum`, `min`, `max`, `avg`, `std_dev`, `std_var`, and so on.
13	`vectorAggregateParam`: The parameter for the vector aggregate function, such as `topk(10, count_over_time({source=foo} [1m])`.
14	`vectorAggregateGrouping`: The grouping for the vector aggregate.
15	`TimeSeries`: The returned time series data, including the following: `points` (Individual datapoints, constructed from a timestamp and float value) `tags` (Map)

Examples

Initial request

subscription {
  getLogMetricsTimeSeriesStream(
    durationMs: 300000
    lookBackMs: 5000
    stepMs: 5000
    logQuery: {and: [{ and: [{ eq: { facetName: "level", value: "info" } }{ eq: { facetName: "source", value: "apigateway" } }] }]},
    rangeAggregate: "count_over_time"
    vectorAggregate: "sum"
    vectorAggregateGrouping: {
      groups: ["level"]
    }
    timestamp: "2025-04-08T12:17:13-07:00",
  ) {
    points {
      ts
      value
    }
    tags
    }
}

getLogsV2Stream

Get logs based on time and log filters, with sorting and limit support.

Syntax

subscription { (1)
  getLogsV2Stream(
    timestamp: Time (2)
    durationSecs: Int (3)
    query: LogQuery (4)
    limit: Int (5)
    cursor: String (6)
    sortBy: String (7)
    sortOrder: SortOrder (8)
    timeoutSecs: Int (9)
    options: String (10)
  ): LogEventV2List!  (11)
}

1	`subscription`: This is a subscription; calls return multiple responses.
2	`timestamp`: Beginning of the sampled time frame.
3	`durationSecs`: Unresolved include directive in modules/ROOT/pages/logs-api.adoc - include::../partials/fuseql/durationsecs-argument.adoc[]
4	`query`: Query of logs, including all operators, *except* Window and Aggregation.
5	`limit`: Limit the number of results; defaults to 1000.
6	`cursor`: Pagination cursor. It must be `null` for the first GraphQL query; subsequent queries must include values from the previous response. If the returned cursor is empty, there are no more results left to fetch.
7	`sortBy`: The property to sort the results by; defaults to `count`.
8	`sortOrder`: Ordering of the returned query; defaults to descending order.
9	`timeoutSecs`: Optional query timeout, in seconds; default is 60 seconds.
10	`options`: Query options; string of comma-separated `k=v` key-value pairs. Not implemented — DO NOT USE.
11	`LogEventV2List`: The result list of log events, returning the following: `totalCount` (total number of log events for a given query) `events` (list of log events for a given page) `cursor` ( opaque cursor returned to help in pagination; empty string when no more data to fetch).

Examples

Initial query

subscription{
  getLogsV2Stream(
        cursor: null,
        query: {and: [{ and: [{ eq: { facetName: "level", value: "info" } }{ eq: { facetName: "source", value: "apigateway" } }] }]},
        limit: 200,
        timestamp: "2025-04-08T12:17:13-07:00",
        durationSecs: 300
  ) {
        cursor
        events {
          timestamp
          logLine
          fpString
          fpHash
          level
          labels
          facets {
            name
            dataType
            content
          }
        }
      }
}