openapi: 3.0.3 info: title: Grafana HTTP Access Recording 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: Recording paths: /recording-rules: parameters: [] get: tags: - Recording summary: Grafana List Recording Rules description: This API operation retrieves a list of all recording rules configured in Grafana. Recording rules are used to pre-compute frequently needed or computationally expensive expressions and save their result as a new set of time series data, which can improve query performance and reduce load on data sources. The GET request to the /recording-rules endpoint returns details about existing recording rules including their names, expressions, labels, and associated data sources, allowing administrators and users to view and manage their configured recording rules within the Grafana instance. operationId: listRecordingRules parameters: [] responses: '200': description: (empty) headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/RecordingRuleJSON' description: '' contentMediaType: application/json '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' '404': description: NotFoundError is returned when the requested resource was not found. 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 put: tags: - Recording summary: Grafana Update Recording Rule description: Updates an existing recording rule in Grafana's alerting system. Recording rules are used to pre-calculate frequently needed or computationally expensive expressions and save their results as a new set of time series. This operation allows you to modify the configuration of a recording rule including its query expressions, labels, evaluation interval, and other parameters. You need to provide the complete updated recording rule configuration in the request body, and the rule will be identified by its UID or name. This is commonly used when you need to adjust the recording rule's query, change its labels, modify the evaluation frequency, or update any other aspect of how the rule processes and stores metric data. Proper authentication and appropriate permissions are required to perform this operation. operationId: updateRecordingRule parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/RecordingRuleJSON' required: true responses: '200': description: (empty) headers: {} content: application/json: schema: $ref: '#/components/schemas/RecordingRuleJSON' '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' '404': description: NotFoundError is returned when the requested resource was not found. 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 post: tags: - Recording summary: Grafana Create Recording Rule description: Creates a new recording rule in Grafana's alerting system that allows you to pre-compute frequently needed or computationally expensive expressions and save their result as a new set of time series. This POST endpoint accepts a recording rule definition including the rule name, query expression, labels, and evaluation interval, then stores it in the Grafana instance for continuous evaluation. Recording rules are particularly useful for dashboard performance optimization and creating aggregated metrics that can be queried more efficiently than running complex calculations repeatedly. operationId: createRecordingRule parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/RecordingRuleJSON' required: true responses: '200': description: (empty) headers: {} content: application/json: schema: $ref: '#/components/schemas/RecordingRuleJSON' '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' '404': description: NotFoundError is returned when the requested resource was not found. 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 /recording-rules/test: parameters: [] post: tags: - Recording summary: Grafana Test Create Recording Rule description: This API operation allows users to test the creation of a recording rule in Grafana before actually implementing it. By sending a POST request to the /recording-rules/test endpoint, users can validate their recording rule configuration, including the PromQL expression, labels, and other parameters, to ensure it functions as expected without permanently adding it to the system. This testing capability helps prevent errors and allows users to verify that their recording rule will produce the desired metrics aggregation or computation results in their monitoring setup before committing the changes to their Grafana instance. operationId: testCreateRecordingRule parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/RecordingRuleJSON' required: true responses: '200': description: An OKResponse is returned if the request was successful. headers: {} content: application/json: schema: $ref: '#/components/schemas/SuccessResponseBody' '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' '404': description: NotFoundError is returned when the requested resource was not found. headers: {} content: application/json: schema: $ref: '#/components/schemas/ErrorResponseBody' '422': description: UnprocessableEntityError 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 /recording-rules/writer: parameters: [] get: tags: - Recording summary: Grafana Get Recording Rule Write Target description: This API operation retrieves the configured write target for recording rules in Grafana. When called using a GET request to the /recording-rules/writer endpoint, it returns information about where recording rule data is being written, which typically includes details about the remote write configuration or storage backend that has been set up to receive and store the results of recording rule evaluations. This is useful for administrators who need to verify or audit the destination of their recording rule outputs. operationId: getRecordingRuleWriteTarget parameters: [] responses: '200': description: (empty) headers: {} content: application/json: schema: $ref: '#/components/schemas/PrometheusRemoteWriteTargetJSON' '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' '404': description: NotFoundError is returned when the requested resource was not found. 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 post: tags: - Recording summary: Grafana Create Recording Rule Write Target description: The POST operation on the /recording-rules/writer endpoint in Grafana allows administrators to create a new recording rule write target, which defines a destination where pre-computed metric aggregations (recording rules) should be written. This endpoint accepts configuration details such as the remote write URL, authentication credentials, and other parameters necessary to establish a connection with the target storage system. Recording rule write targets enable Grafana to send the results of recording rule evaluations to external time-series databases or other compatible endpoints, facilitating data distribution, backup strategies, or multi-tenancy scenarios where recording rule results need to be persisted or forwarded to different storage backends. operationId: createRecordingRuleWriteTarget parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/PrometheusRemoteWriteTargetJSON' required: true responses: '200': description: (empty) headers: {} content: application/json: schema: $ref: '#/components/schemas/PrometheusRemoteWriteTargetJSON' '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' '404': description: NotFoundError is returned when the requested resource was not found. headers: {} content: application/json: schema: $ref: '#/components/schemas/ErrorResponseBody' '422': description: UnprocessableEntityError 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 delete: tags: - Recording summary: Grafana Delete Recording Rule Write Target description: This API operation removes a configured recording rule write target from Grafana. Recording rule write targets define external destinations where pre-aggregated metric data can be stored, and deleting a write target will disconnect Grafana from that specific storage endpoint. This DELETE operation is typically used when decommissioning a remote write destination, cleaning up unused configurations, or reconfiguring the recording rules infrastructure. Once deleted, recording rules will no longer write their computed results to the removed target location. operationId: deleteRecordingRuleWriteTarget parameters: [] responses: '200': description: An OKResponse is returned if the request was successful. headers: {} content: application/json: schema: $ref: '#/components/schemas/SuccessResponseBody' '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' '404': description: NotFoundError is returned when the requested resource was not found. 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 /recording-rules/{recordingRuleID}: parameters: [] delete: tags: - Recording summary: Grafana Delete Recording Rule description: Deletes a specific recording rule from Grafana by providing its unique identifier in the request path. Recording rules are used to pre-compute frequently needed or computationally expensive expressions and save their results as new time series data. This DELETE operation permanently removes the recording rule configuration identified by the recordingRuleID parameter, stopping any future evaluations and recordings associated with that rule. The operation requires appropriate authentication and authorization permissions to modify recording rule configurations in the Grafana instance. operationId: deleteRecordingRule parameters: - name: recordingRuleID in: path description: '' required: true schema: type: integer contentEncoding: int64 responses: '200': description: An OKResponse is returned if the request was successful. headers: {} content: application/json: schema: $ref: '#/components/schemas/SuccessResponseBody' '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' '404': description: NotFoundError is returned when the requested resource was not found. 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: 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.' PrometheusRemoteWriteTargetJSON: title: PrometheusRemoteWriteTargetJSON type: object properties: data_source_uid: type: string id: type: string remote_write_path: type: string SuccessResponseBody: title: SuccessResponseBody type: object properties: message: type: string RecordingRuleJSON: title: RecordingRuleJSON type: object properties: active: type: boolean count: type: boolean description: type: string dest_data_source_uid: type: string id: type: string interval: type: integer contentEncoding: int64 name: type: string prom_name: type: string queries: type: array items: {} description: '' range: type: integer contentEncoding: int64 target_ref_id: type: string description: RecordingRuleJSON is the external representation of a recording rule 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 '