openapi: 3.0.3 info: title: Grafana HTTP Access Metrics API description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header. version: 11.0.0 contact: name: Grafana Labs url: https://grafana.com license: name: AGPL-3.0 url: https://www.gnu.org/licenses/agpl-3.0.html servers: - url: https://{instance}.grafana.net/api description: Grafana Cloud variables: instance: default: your-instance - url: http://localhost:3000/api description: Local Grafana instance security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - name: Metrics paths: /ds/query: parameters: [] post: tags: - Metrics summary: Grafana Query Metrics With Expressions description: This API operation enables querying of metrics data in Grafana using the datasource query endpoint, supporting advanced query expressions and transformations. It accepts POST requests at the /ds/query endpoint and allows users to execute complex queries against configured data sources, combining multiple queries with mathematical expressions, statistical functions, and data transformations to derive meaningful insights from time-series data. The operation supports various datasource types and returns formatted query results that can be visualized in Grafana dashboards, making it essential for creating dynamic panels with calculated metrics, aggregations, and custom data manipulations. operationId: queryMetricsWithExpressions parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/MetricRequest' required: true responses: '200': description: (empty) headers: {} content: application/json: schema: $ref: '#/components/schemas/QueryDataResponsecontainstheresultsfromaQueryDataRequest.' '207': description: (empty) headers: {} content: application/json: schema: $ref: '#/components/schemas/QueryDataResponsecontainstheresultsfromaQueryDataRequest.' '400': description: BadRequestError is returned when the request is invalid and it cannot be processed. headers: {} content: application/json: schema: $ref: '#/components/schemas/ErrorResponseBody' '401': description: UnauthorizedError is returned when the request is not authenticated. headers: {} content: application/json: schema: $ref: '#/components/schemas/ErrorResponseBody' '403': description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource. headers: {} content: application/json: schema: $ref: '#/components/schemas/ErrorResponseBody' '500': description: InternalServerError is a general error indicating something went wrong internally. headers: {} content: application/json: schema: $ref: '#/components/schemas/ErrorResponseBody' deprecated: false x-api-evangelist-processing: SplitPascalCaseOperationSummaries: true CaselCaseOperationIds: true WriteDescription: true ChooseTags: true components: schemas: QueryDataResponsecontainstheresultsfromaQueryDataRequest.: title: QueryDataResponsecontainstheresultsfromaQueryDataRequest. type: object properties: results: type: object additionalProperties: $ref: '#/components/schemas/DataResponsecontainstheresultsfromaDataQuery.' description: 'The QueryData method the QueryDataHandler method will set the RefId property on the DataResponses'' frames based on these RefIDs.' description: It is the return type of a QueryData call. QueryStatisusedforstoringarbitrarystatisticsmetadatarelatedtoaqueryanditsresulte.g.totalrequesttimedataprocessingtime.: title: QueryStatisusedforstoringarbitrarystatisticsmetadatarelatedtoaqueryanditsresulte.g.totalrequesttimedataprocessingtime. type: object properties: color: type: object additionalProperties: {} description: 'Map values to a display color NOTE: this interface is under development in the frontend... so simple map for now' custom: type: object additionalProperties: {} description: Panel Specific Values decimals: type: integer contentEncoding: int32 description: type: string description: Description is human readable field metadata displayName: type: string description: DisplayName overrides Grafana default naming, should not be used from a data source displayNameFromDS: type: string description: DisplayNameFromDS overrides Grafana default naming strategy. filterable: type: boolean description: Filterable indicates if the Field's data can be filtered by additional calls. interval: type: number description: 'Interval indicates the expected regular step between values in the series. When an interval exists, consumers can identify "missing" values when the expected value is not present. The grafana timeseries visualization will render disconnected values when missing values are found it the time field. The interval uses the same units as the values. For time.Time, this is defined in milliseconds.' links: type: array items: $ref: '#/components/schemas/DataLink' description: The behavior when clicking on a result mappings: type: array items: type: object description: '' max: type: number description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf to null.' min: type: number description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf to null.' noValue: type: string description: Alternative to empty string path: type: string description: 'Path is an explicit path to the field in the datasource. When the frame meta includes a path, this will default to `${frame.meta.path}/${field.name} When defined, this value can be used as an identifier within the datasource scope, and may be used as an identifier to update values in a subsequent request' thresholds: allOf: - $ref: '#/components/schemas/ThresholdsConfig' - description: ThresholdsConfig setup thresholds type: allOf: - $ref: '#/components/schemas/FieldTypeConfig' - description: FieldTypeConfig has type specific configs, only one should be active at a time unit: type: string description: Numeric Options value: type: number writeable: type: boolean description: Writeable indicates that the datasource knows how to update this value description: 'The embedded FieldConfig''s display name must be set. It corresponds to the QueryResultMetaStat on the frontend (https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L53).' LinkTransformationConfig: title: LinkTransformationConfig type: object properties: expression: type: string field: type: string mapValue: type: string type: type: string ThresholdsConfig: title: ThresholdsConfig type: object properties: mode: type: string description: ThresholdsMode absolute or percentage steps: type: array items: $ref: '#/components/schemas/Threshold' description: Must be sorted by 'value', first value is always -Infinity description: ThresholdsConfig setup thresholds DataLink: title: DataLink type: object properties: internal: allOf: - $ref: '#/components/schemas/InternalDataLink' - description: InternalDataLink definition to allow Explore links to be constructed in the backend targetBlank: type: boolean title: type: string url: type: string description: DataLink define what FieldConfigrepresentsthedisplaypropertiesforaField.: title: FieldConfigrepresentsthedisplaypropertiesforaField. type: object properties: color: type: object additionalProperties: {} description: 'Map values to a display color NOTE: this interface is under development in the frontend... so simple map for now' custom: type: object additionalProperties: {} description: Panel Specific Values decimals: type: integer contentEncoding: int32 description: type: string description: Description is human readable field metadata displayName: type: string description: DisplayName overrides Grafana default naming, should not be used from a data source displayNameFromDS: type: string description: DisplayNameFromDS overrides Grafana default naming strategy. filterable: type: boolean description: Filterable indicates if the Field's data can be filtered by additional calls. interval: type: number description: 'Interval indicates the expected regular step between values in the series. When an interval exists, consumers can identify "missing" values when the expected value is not present. The grafana timeseries visualization will render disconnected values when missing values are found it the time field. The interval uses the same units as the values. For time.Time, this is defined in milliseconds.' links: type: array items: $ref: '#/components/schemas/DataLink' description: The behavior when clicking on a result mappings: type: array items: type: object description: '' max: type: number description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf to null.' min: type: number description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf to null.' noValue: type: string description: Alternative to empty string path: type: string description: 'Path is an explicit path to the field in the datasource. When the frame meta includes a path, this will default to `${frame.meta.path}/${field.name} When defined, this value can be used as an identifier within the datasource scope, and may be used as an identifier to update values in a subsequent request' thresholds: allOf: - $ref: '#/components/schemas/ThresholdsConfig' - description: ThresholdsConfig setup thresholds type: allOf: - $ref: '#/components/schemas/FieldTypeConfig' - description: FieldTypeConfig has type specific configs, only one should be active at a time unit: type: string description: Numeric Options writeable: type: boolean description: Writeable indicates that the datasource knows how to update this value EnumFieldConfig: title: EnumFieldConfig type: object properties: color: type: array items: type: string description: Color is the color value for a given index (empty is undefined) description: type: array items: type: string description: Description of the enum state icon: type: array items: type: string description: Icon supports setting an icon for a given index value text: type: array items: type: string description: Value is the string display value for a given index description: 'Enum field config Vector values are used as lookup keys into the enum fields' FrameisacolumnardatastructurewhereeachcolumnisaField.: title: FrameisacolumnardatastructurewhereeachcolumnisaField. type: object properties: Fields: type: array items: $ref: '#/components/schemas/FieldrepresentsatypedcolumnofdatawithinaFrame.' description: 'Fields are the columns of a frame. All Fields must be of the same the length when marshalling the Frame for transmission. There should be no `nil` entries in the Fields slice (making them pointers was a mistake).' Meta: allOf: - $ref: '#/components/schemas/FrameMetamatches' - description: 'https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L11 NOTE -- in javascript this can accept any `[key: string]: any;` however this interface only exposes the values we want to be exposed' Name: type: string description: Name is used in some Grafana visualizations. RefID: type: string description: RefID is a property that can be set to match a Frame to its originating query. description: 'Each Field is well typed by its FieldType and supports optional Labels. A Frame is a general data container for Grafana. A Frame can be table data or time series data depending on its content and field types.' FieldTypeConfig: title: FieldTypeConfig type: object properties: enum: allOf: - $ref: '#/components/schemas/EnumFieldConfig' - description: 'Enum field config Vector values are used as lookup keys into the enum fields' description: FieldTypeConfig has type specific configs, only one should be active at a time TimeRange: title: TimeRange type: object properties: from: type: string contentEncoding: date-time to: type: string contentEncoding: date-time description: Redefining this to avoid an import cycle Threshold: title: Threshold type: object properties: color: type: string state: type: string value: type: number description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf to null.' description: Threshold a single step on the threshold list MetricRequest: title: MetricRequest required: - from - queries - to type: object properties: debug: type: boolean from: type: string description: From Start time in epoch timestamps in milliseconds or relative using Grafana time units. examples: - now-1h queries: type: array items: type: object description: 'queries.refId – Specifies an identifier of the query. Is optional and default to “A”. queries.datasourceId – Specifies the data source to be queried. Each query in the request must have an unique datasourceId. queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100. queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.' examples: - - datasource: uid: PD8C576611E62080A format: table intervalMs: 86400000 maxDataPoints: 1092 rawSql: SELECT 1 as valueOne, 2 as valueTwo refId: A to: type: string description: To End time in epoch timestamps in milliseconds or relative using Grafana time units. examples: - now DataResponsecontainstheresultsfromaDataQuery.: title: DataResponsecontainstheresultsfromaDataQuery. type: object properties: Error: type: string description: Error is a property to be set if the corresponding DataQuery has an error. ErrorSource: type: string Frames: type: array items: $ref: '#/components/schemas/FrameisacolumnardatastructurewhereeachcolumnisaField.' description: 'It is the main data container within a backend.DataResponse. There should be no `nil` entries in the Frames slice (making them pointers was a mistake).' Status: type: integer contentEncoding: int64 description: 'A map of RefIDs (unique query identifiers) to this type makes up the Responses property of a QueryDataResponse. The Error property is used to allow for partial success responses from the containing QueryDataResponse.' FrameMetamatches: title: FrameMetamatches type: object properties: channel: type: string description: Channel is the path to a stream in grafana live that has real-time updates for this data. custom: description: Custom datasource specific values. dataTopic: type: string description: nolint:revive executedQueryString: type: string description: 'ExecutedQueryString is the raw query sent to the underlying system. All macros and templating have been applied. When metadata contains this value, it will be shown in the query inspector.' notices: type: array items: $ref: '#/components/schemas/NoticeprovidesastructureforpresentingnotificationsinGrafanasuserinterface.' description: 'Notices provide additional information about the data in the Frame that Grafana can display to the user in the user interface.' path: type: string description: Path is a browsable path on the datasource. pathSeparator: type: string description: PathSeparator defines the separator pattern to decode a hierarchy. The default separator is '/'. preferredVisualisationPluginId: type: string description: 'PreferredVisualizationPluginId sets the panel plugin id to use to render the data when using Explore. If the plugin cannot be found will fall back to PreferredVisualization.' preferredVisualisationType: type: string stats: type: array items: $ref: '#/components/schemas/QueryStatisusedforstoringarbitrarystatisticsmetadatarelatedtoaqueryanditsresulte.g.totalrequesttimedataprocessingtime.' description: Stats is an array of query result statistics. type: type: string description: 'A FrameType string, when present in a frame''s metadata, asserts that the frame''s structure conforms to the FrameType''s specification. This property is currently optional, so FrameType may be FrameTypeUnknown even if the properties of the Frame correspond to a defined FrameType. +enum' typeVersion: type: array items: type: integer contentEncoding: int32 description: '' uniqueRowIdFields: type: array items: type: integer contentEncoding: int64 description: 'Array of field indices which values create a unique id for each row. Ideally this should be globally unique ID but that isn''t guarantied. Should help with keeping track and deduplicating rows in visualizations, especially with streaming data with frequent updates.' description: 'https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L11 NOTE -- in javascript this can accept any `[key: string]: any;` however this interface only exposes the values we want to be exposed' ErrorResponseBody: title: ErrorResponseBody required: - message type: object properties: error: type: string description: Error An optional detailed description of the actual error. Only included if running in developer mode. message: type: string description: a human readable version of the error status: type: string description: 'Status An optional status to denote the cause of the error. For example, a 412 Precondition Failed error may include additional information of why that error happened.' NoticeprovidesastructureforpresentingnotificationsinGrafanasuserinterface.: title: NoticeprovidesastructureforpresentingnotificationsinGrafanasuserinterface. type: object properties: inspect: type: integer contentEncoding: int64 link: type: string description: 'Link is an optional link for display in the user interface and can be an absolute URL or a path relative to Grafana''s root url.' severity: type: integer contentEncoding: int64 text: type: string description: Text is freeform descriptive text for the notice. InternalDataLink: title: InternalDataLink type: object properties: datasourceName: type: string datasourceUid: type: string panelsState: description: This is an object constructed with the keys as the values of the enum VisType and the value being a bag of properties query: {} timeRange: allOf: - $ref: '#/components/schemas/TimeRange' - description: Redefining this to avoid an import cycle transformations: type: array items: $ref: '#/components/schemas/LinkTransformationConfig' description: '' description: InternalDataLink definition to allow Explore links to be constructed in the backend FieldrepresentsatypedcolumnofdatawithinaFrame.: title: FieldrepresentsatypedcolumnofdatawithinaFrame. type: object properties: config: $ref: '#/components/schemas/FieldConfigrepresentsthedisplaypropertiesforaField.' labels: type: object additionalProperties: type: string description: Labels are used to add metadata to an object. The JSON will always be sorted keys name: type: string description: 'Name is default identifier of the field. The name does not have to be unique, but the combination of name and Labels should be unique for proper behavior in all situations.' description: 'A Field is essentially a slice of various types with extra properties and methods. See NewField() for supported types. The slice data in the Field is a not exported, so methods on the Field are used to to manipulate its data.' securitySchemes: BearerAuth: type: http scheme: bearer description: Service account token or API key BasicAuth: type: http scheme: basic ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Format: Bearer '