> ## Documentation Index > Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Invoke datasource tool > Execute one deterministic diagnostic or query tool against a configured datasource. ## Restrictions | Aspect | Value | | ----------- | ------------------------------------------------------------- | | Rate limits | **2,000 requests/minute**; **32 requests/second** per account | | Permissions | **Datasources Read** (`monit`) | Use datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically. ## Usage * Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `.query`. The tool prefix must match the datasource type. * Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically. * For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded. * Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`. * Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds. ## OpenAPI ````yaml /api-reference/monitors.openapi.en.json post /monit/datasource/tools/invoke openapi: 3.1.0 info: title: Flashduty Open API description: >- Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure. version: 1.0.0 servers: - url: https://api.flashcat.cloud description: Flashduty Open API security: - AppKeyAuth: [] tags: - name: Monitors/Alert rules description: >- Create, manage, and export monitor alert rules. Query rule counters and audit history. - name: Monitors/Data sources description: Manage monitoring data sources used by alert rules to query metrics. - name: Monitors/Diagnostics description: >- Diagnostic and query endpoints used by Flashduty AI SRE — ad-hoc data source queries, log/metric diagnostics, and target-side tool invocation. - name: Monitors/Monitor utilities description: Monitors service activation and data preview utilities. paths: /monit/datasource/tools/invoke: post: tags: - Monitors/Data sources summary: Invoke datasource tool description: >- Execute one deterministic diagnostic or query tool against a configured datasource. operationId: monit-datasource-tools-invoke requestBody: content: application/json: schema: $ref: '#/components/schemas/DatasourceToolInvokeRequest' examples: diagnostic: value: datasource_id: 10 params: {} tool: mysql.overview query: value: datasource_id: 24000 tool: prometheus.query params: expr: sum(rate(http_requests_total[5m])) execution: kind: instant to_ms: 1789000000000 required: true responses: '200': content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/DatasourceToolResult' type: object examples: diagnostic: value: data: data: version: 8.0.36 datasource_id: 10 summary: MySQL overview tool: mysql.overview request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 query: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: datasource_id: 24000 tool: prometheus.query data: format: explore_result.v1 result: kind: samples samples: - labels: __name__: up instance: 10.101.214.50:7070 value: 1 description: Success '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Standard HTTP error; error.reason: invalid_request, tool_not_supported, datasource_error. '401': $ref: '#/components/responses/Unauthorized' '403': description: 'Standard HTTP error; error.reason: access_denied.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 'Standard HTTP error; error.reason: datasource_not_found.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Standard HTTP error; error.reason: datasource_disabled, datasource_in_use. '413': description: >- Standard HTTP error; error.reason: source_too_large, result_too_large. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: 'Standard HTTP error; error.reason: overloaded.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '499': description: 'Standard HTTP error; error.reason: canceled.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Standard HTTP error; error.reason: internal.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Standard HTTP error; error.reason: no_active_edge, edge_upgrade_required, mixed_edge_versions. '504': description: 'Standard HTTP error; error.reason: timeout.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: DatasourceToolInvokeRequest: properties: account_id: description: Optional consistency check; must equal the authenticated account. format: uint64 type: integer datasource_id: description: Datasource ID from /monit/datasource/list. format: uint64 minimum: 1 type: integer params: additionalProperties: true description: >- Tool-specific JSON parameters; omitted means {}. Explicit null is invalid. Query tools (`.query`) use the per-datasource params schemas named in the `tool` description. type: object x-flashduty-raw-json: true tool: description: >- Single tool name prefixed by the datasource type. Diagnostic tools are defined by the executing Edge (e.g. `mysql.overview`). Query tools are `.query` where `` is one of `prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`; their `params` follow `PrometheusQueryParams`, `MySQLQueryParams`, `PostgresQueryParams`, `OracleQueryParams`, `ClickHouseQueryParams`, `ElasticsearchQueryParams`, `LokiQueryParams`, `VictoriaLogsQueryParams`, `SLSQueryParams`, or `TencentCLSQueryParams` respectively. maxLength: 128 minLength: 1 type: string required: - datasource_id - tool type: object SuccessEnvelope: type: object description: >- 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`. properties: request_id: type: string description: >- Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues. example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: description: Endpoint-specific payload. See each operation's 200 response schema. required: - request_id - data DatasourceToolResult: properties: data: description: >- Tool-specific JSON evidence, preserved without conversion; never null. No nested legacy diagnose envelope. not: type: 'null' x-flashduty-raw-json: true datasource_id: description: Datasource ID from /monit/datasource/list. format: uint64 minimum: 1 type: integer summary: description: Optional non-empty summary. type: string x-flashduty-preserve-absence: true tool: description: Executed tool name matching the request. type: string truncated: $ref: '#/components/schemas/DatasourceToolTruncation' x-flashduty-preserve-absence: true required: - datasource_id - tool - data type: object ErrorResponse: type: object description: Response envelope for errors. `error` is required; `data` is absent. properties: request_id: type: string example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 description: >- Unique trace ID of this request; include it when reporting issues so logs can be located. error: $ref: '#/components/schemas/DutyError' required: - request_id - error DatasourceToolTruncation: properties: reason: description: >- Why the result was truncated. Presence of this object indicates truncation. type: string required: - reason type: object DutyError: type: object description: >- Error payload inside the response envelope. Present only on non-2xx responses. properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request. example: The specified parameter template_id is not valid. reason: description: >- Optional machine-readable rejection reason, including datasource tool failures. Inspect alongside HTTP status and code. type: string x-flashduty-preserve-absence: true required: - code - message ErrorCode: type: string description: >- Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value. | Code | HTTP | Meaning | |---|---|---| | `OK` | 200 | Reserved — not returned on real errors. | | `InvalidParameter` | 400 | A required parameter is missing or failed validation. | | `BadRequest` | 400 | Generic 400 used when no more specific code fits. | | `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. | | `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). | | `NoLicense` | 400 | The feature is license-gated and no active license was found. | | `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. | | `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. | | `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. | | `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. | | `RouteNotFound` | 404 | The request URL path is not a known route. | | `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. | | `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. | | `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. | | `EntityTooLarge` | 413 | Request body exceeds the configured max size. | | `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. | | `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. | | `DangerousOperation` | 428 | High-risk operation requires MFA verification. | | `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. | | `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - RequestLocked - EntityTooLarge - RequestTooFrequently - RequestVerifyRequired - DangerousOperation - InternalError - ServiceUnavailable x-enumDescriptions: OK: Reserved — not returned on real errors. InvalidParameter: A required parameter is missing or failed validation. BadRequest: Generic 400 used when no more specific code fits. InvalidContentType: The `Content-Type` header is not `application/json`. ResourceNotFound: >- The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). NoLicense: The feature is license-gated and no active license was found. ReferenceExist: Deletion blocked — other entities still reference this resource. Unauthorized: '`app_key` is missing, invalid, or expired.' BalanceNotEnough: Billing-gated operation with insufficient account balance. AccessDenied: Authenticated but lacking the permission required for this operation. RouteNotFound: The request URL path is not a known route. MethodNotAllowed: The HTTP method is not allowed on this otherwise-known path. UndonedOrderExist: An outstanding billing order blocks this new one. Wait and retry. RequestLocked: Operation temporarily locked due to repeated failures. EntityTooLarge: Request body exceeds the configured max size. RequestTooFrequently: Rate limit hit — API-global, per-account, or per-integration. RequestVerifyRequired: Second-factor verification required but not supplied. DangerousOperation: High-risk operation requires MFA verification. InternalError: Unhandled server-side error. Include `request_id` in the bug report. ServiceUnavailable: A backend dependency is unavailable. Try again later. example: InvalidParameter responses: Unauthorized: description: Missing or invalid app_key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAppKey: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: Unauthorized message: You are unauthorized. securitySchemes: AppKeyAuth: type: apiKey in: query name: app_key description: >- App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account. ````