# 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](https://docs.kloudfuse.com/platform/3.2.5/graphql/).

For authorization, see [Authorization for API calls](https://docs.kloudfuse.com/platform/3.2.5/authorization-api/).

## Supported queries

[getFacetValueCountsStream](https://docs.kloudfuse.com/platform/3.2.5/logs-api/#getFacetValueCountsStream)

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

[getLabelValuesStream](https://docs.kloudfuse.com/platform/3.2.5/logs-api/#getLabelValuesStream)

Get label values for the specified label name.

[getLogMetricsTimeSeries](https://docs.kloudfuse.com/platform/3.2.5/logs-api/#getLogMetricsTimeSeries)

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

[getLogMetricsTimeSeriesStream](https://docs.kloudfuse.com/platform/3.2.5/logs-api/#getLogMetricsTimeSeriesStream)

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

[getLogsV2Stream](https://docs.kloudfuse.com/platform/3.2.5/logs-api/#getLogsV2Stream)

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

## Prerequisites

- Configure a GraphQL client. See [GraphQL](https://www.graphql-js.org/docs/graphql-clients/) documentation.

- Authenticate using the basic HTTP authentication protocol.

## getFacetValueCountsStream

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

### Syntax

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

### Examples

Initial query

```code
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

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

### Examples

Initial query

```code
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

```code
{ (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)
}
```

### Examples

Initial request

```code
{
  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

```code
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)
}
```

### Examples

Initial request

```code
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

```code
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)
}
```

### Examples

Initial query

```code
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
          }
        }
      }
}
```