# API for Logs
## Endpoint
Use the APIs in this section with the `/query` endpoint.
## Supported queries
### getFacetValueCountsStream
Get count facet values for the specified time range, with filter support.
**Syntax**
```javascript
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 operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/window-operators/) and [Aggregation operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/aggregation-operators/). |
| **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
```javascript
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**
```javascript
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 operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/window-operators/) and [Aggregation operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/aggregation-operators/). |
| **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
```javascript
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**
```javascript
{ (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 operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/window-operators/) and [Aggregation operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/aggregation-operators/). |
| **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 argument, 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
```javascript
{
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**
```javascript
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 operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/window-operators/) and [Aggregation operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/aggregation-operators/). |
| **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
```javascript
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**
```javascript
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`**:
Going back duration in seconds; defaults to 300 seconds. |
| **4** | **`query`**:
Query of logs, including all operators, **_except_** [Window operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/window-operators/) and [Aggregation operators](https://docs.kloudfuse.com/platform/4.1.0/query-languages/fuseql/aggregation-operators/). |
| **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
```javascript
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
}
}
}
}
```