Skip to main content
POST
Query structured data

Restrictions

Usage

  • The data source is identified by ds_type plus ds_name, not by ID. It must belong to the account and be enabled. When the data source restricts querying to certain teams, only members of those teams, its managing team, and account owners or admins can query it; others get AccessDenied.
  • Treat monit-edge v0.65.0 as the minimum supported Edge version for this public API. WebAPI retains migration adapters for older Edge versions: query.v2 results may still preserve frames, records, or samples, while legacy rows can expose only the information they retained. These adapters do not change the support floor; older protocols lack query.v3 cancellation and error-lifecycle semantics, and data already lost by legacy rows cannot be recovered.
  • The public response format is always query_result.v1 and is independent of the internal Edge query protocol. Dispatch on result.kind (frames, records, or samples); do not infer the result shape from ds_type or the Edge version.
  • A frames result may contain multiple table or time-series frames. Field values are columnar and all fields in one frame have the same length.
  • A records result may contain nested JSON and null records. Integer literals outside JavaScript’s safe integer range are returned as decimal strings.
  • A samples result contains label sets and instant values. A value may be a number or one of the strings NaN, +Inf, and -Inf.
  • Prometheus expressions are syntax-checked before the query is dispatched; an invalid expression returns HTTP 400.
  • The request body is limited to 256 KiB and the complete success response to 10 MiB; either limit returns HTTP 413. A result with more than 1,000 rows fails with HTTP 400. Narrow the time range, reduce fields, or aggregate at the source.
  • Query failures use non-2xx HTTP status codes and the standard error envelope.
  • Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds and propagate cancellation when the caller abandons a query.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Request body of the structured query endpoint.

ds_type
enum<string>
required

Data source type. Together with ds_name it must match an enabled data source of the account.

  • prometheus: Prometheus-compatible data source; expr is PromQL.
  • loki: Grafana Loki; expr is LogQL.
  • victorialogs: VictoriaLogs.
  • sls: Alibaba Cloud Log Service (SLS).
  • tencent_cls: Tencent Cloud Log Service (CLS); requires monit-edge v0.66.0 or later.
  • elasticsearch: Elasticsearch.
  • mysql: MySQL; expr is SQL.
  • postgres: PostgreSQL; expr is SQL.
  • oracle: Oracle Database; expr is SQL.
  • clickhouse: ClickHouse; expr is SQL.

Other data source types (for example MongoDB, Redis, or Kafka) are rejected.

Available options:
clickhouse,
elasticsearch,
loki,
mysql,
oracle,
postgres,
prometheus,
sls,
tencent_cls,
victorialogs
ds_name
string
required

Data source name, as returned by /monit/datasource/list. The data source must be enabled; a name that matches no data source of the account returns HTTP 400.

expr
string
required

Query expression in the language of ds_type (PromQL for prometheus, LogQL for loki, SQL for SQL sources, and so on). Required, at most 64 KiB (12 KiB for tencent_cls). Loki's $__auto is not supported here; use a fixed duration such as [5m]. Prometheus expressions are syntax-checked before dispatch.

Minimum string length: 1
account_id
integer<int64>

Optional consistency check. When supplied it must equal the authenticated account, otherwise the request fails with AccessDenied. The query always runs as the authenticated account.

delay_seconds
integer
default:0

Look-back offset in seconds, from 0 to 86400. Applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats); ignored for raw and detail queries. When args carries an absolute <source>.time and the Edge is v0.74.0 or later, the absolute time takes precedence and this offset is not applied.

Required range: 0 <= x <= 86400
args
object

Extra query parameters as string key/value pairs; keys are namespaced by data source (for example sls.project, loki.type). At most 128 entries, keys up to 256 bytes, values up to 64 KiB, and 128 KiB in total. What is accepted depends on ds_type:

  • prometheus: optional prometheus.time, the evaluation time as Unix seconds, not in the future.
  • loki, victorialogs: <source>.type is stats (default) or raw. stats accepts an optional <source>.time (Unix seconds, not in the future). raw requires a time range, either <source>.start + <source>.end (Unix seconds) or <source>.timespan.value + <source>.timespan.unit (s, m, h, or d), spanning at most 6 hours, and accepts <source>.limit from 1 to 1001.
  • sls: sls.project and sls.logstore are required. Optional: sls.lines (1 to 100), sls.offset (0 or more), and a time range of at most 6 hours given as sls.from + sls.to (Unix seconds) or sls.timespan.value + sls.timespan.unit.
  • tencent_cls: tencent_cls.region, tencent_cls.topic_id, tencent_cls.query_mode (raw or analysis), and tencent_cls.syntax (cql or lucene) are required. Optional: tencent_cls.limit (1 to 100, raw mode only, needs monit-edge v0.67.0 or later) and a time range given as tencent_cls.from + tencent_cls.to (Unix seconds) or tencent_cls.timespan.value + tencent_cls.timespan.unit, at most 6 hours in raw mode and 24 hours in analysis mode. Any other key is rejected.
  • elasticsearch: es.type may be sql or omitted; any other value is rejected.
  • mysql, postgres, oracle, clickhouse: no arguments are defined.

An absolute <source>.time is only valid for its own data source type. Edges older than v0.74.0 approximate it with a look-back offset and accept only times within the last 86,400 seconds.

Response

Success

Success response envelope. On every 2xx response, request_id identifies the call (also mirrored in the Flashcat-Request-Id header) and data holds the endpoint-specific payload. Failure responses use a different shape — see ErrorResponse.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

Stable, Edge-version-independent structured query response.