docs/sources/upgrade-guide/upgrade-v13.0/index.md
{{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
{{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< admonition type="warning" >}} GitSync early adopters: if you enabled GitSync in Grafana v12.x.x, do not upgrade to Grafana v13.0.0. A migration bug can cause dashboards and folders to be lost or reverted during the upgrade.
This bug only affects self-managed instances that enabled the GitSync feature flags (provisioning, kubernetesClientDashboardsFolders, kubernetesDashboards, and grafanaAPIServerEnsureKubectlAccess) before GitSync reached general availability.
Grafana v13.0.0 was removed from distribution and a fix is being prepared for Grafana v13.0.1.
If you already upgraded and are affected, recovery might require restoring from backup or resyncing from Git, depending on whether your instance used mixed local/GitSync content or full-instance sync.
We recommend using your database backup to restore and then upgrading to 13.0.1. {{< /admonition >}}
As part of the migration to React 19 in Grafana 13, make the following updates to ensure that your plugins are working properly and you don't experience any disruptions during the Grafana 13 upgrade.
Follow this sequence for best results:
To ensure that the changes required for the upgrade to React 19 are in place in your Grafana version, update to the latest minor version available for your Grafana instance. You can check the available versions on the downloads page.
Update all of your installed plugins and check if they are still working properly. By using the latest version of a plugin you facilitate support to React 19.
Finally you can continue your upgrade to Grafana 13.
/api endpoints are now deprecatedThe new Kubernetes-style API for dashboards, folders, and annotations is generally available in Grafana v13.0. The legacy /api endpoints are deprecated and will be removed in a future major release.
The new API is built on the Grafana App Platform (Kubernetes resource model) and provides versioned, consistent, and schema-based endpoints. The legacy /api endpoints remain functional but won't receive new features.
The new API paths include a {namespace} parameter. The value depends on your deployment type:
my-stack).org-1).The dashboards API is deprecated in Grafana v13.0. The new v1 API is available now.
New API reference: {your-instance}/swagger?api=dashboard.grafana.app-v1
| Operation | Legacy endpoint | New endpoint |
|---|---|---|
| Get dashboard | GET /api/dashboards/uid/{uid} | GET /apis/dashboard.grafana.app/v1/namespaces/{namespace}/dashboards/{uid} |
| Create or update | POST /api/dashboards/db | POST /apis/dashboard.grafana.app/v1/namespaces/{namespace}/dashboards |
| Delete dashboard | DELETE /api/dashboards/uid/{uid} | DELETE /apis/dashboard.grafana.app/v1/namespaces/{namespace}/dashboards/{uid} |
| List dashboards | GET /api/search | GET /apis/dashboard.grafana.app/v1/namespaces/{namespace}/dashboards |
| Dashboard versions | GET /api/dashboards/uid/{uid}/versions | Version history is now managed through resource metadata, consistent with the Kubernetes resource model. Use label and field selectors on the dashboards resource: GET /apis/dashboard.grafana.app/v1/namespaces/{namespace}/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name={uid} |
| Dashboard tags | GET /api/dashboards/tags | Deprecated, no replacement planned. |
The folders API is deprecated in Grafana v13.0. The new v1 API is available now.
New API reference: {your-instance}/swagger?api=folder.grafana.app-v1
| Operation | Legacy endpoint | New endpoint |
|---|---|---|
| List folders | GET /api/folders | GET /apis/folder.grafana.app/v1/namespaces/{namespace}/folders |
| Get folder | GET /api/folders/{uid} | GET /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid} |
| Create folder | POST /api/folders | POST /apis/folder.grafana.app/v1/namespaces/{namespace}/folders |
| Update folder | PUT /api/folders/{uid} | PUT /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid} |
| Move folder | POST /api/folders/{uid}/move | PUT /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid} |
| Delete folder | DELETE /api/folders/{uid} | DELETE /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid} |
To move a folder, set the grafana.app/folder annotation to the parent folder UID in the PUT request body.
The annotations API deprecation is in progress. The new annotations API isn't available yet, and the migration path will be announced when it's ready.
/apis/annotation.grafana.app/{apiVersion}/namespaces/{namespace}/annotations. The endpoint mapping will be published when the new API is available.POST /api/annotations/mass-delete isn't supported in the new API and has no equivalent UI feature. Use the new TTL (time to live) configuration to define how long annotations are retained instead of performing bulk deletes.GET /api/annotations/tags is preserved through a dedicated /tags route with the same prefix-based filtering.Audit your current annotation API usage now, particularly any use of mass-delete.
The query history API is deprecated in Grafana v13.0 and will be removed in a future release.
Query history APIs won't be migrated to the Grafana App Platform. Instead, Grafana will revert to using local on-device storage for this functionality.
| Operation | Legacy endpoint | New endpoint |
|---|---|---|
| Create query history | POST /api/query-history | Deprecated, no replacement planned. |
| Fetch query history | GET /api/query-history?{params} | Deprecated, no replacement planned. |
| Delete a query | DELETE /api/query-history/{id} | Deprecated, no replacement planned. |
| Update a comment | PATCH /api/query-history/{id} | Deprecated, no replacement planned. |
| Star a query | POST /api/query-history/star/{id} | Deprecated, no replacement planned. |
| Unstar a query | DELETE /api/query-history/star/{id} | Deprecated, no replacement planned. |
If you consume the query history APIs directly, adopt a local on-device storage approach. A sample implementation will be provided in a future Grafana release that you can use as a reference.
The legacy endpoints continue to work for now. No immediate action is required, but early migration is recommended.
Data source APIs that reference data sources by numeric id have been deprecated since Grafana 9.
In Grafana 13, they're disabled by default.
You use data source API endpoints that reference data sources by numeric id rather than uid.
Update your API calls to reference data sources by uid instead of numeric id.
To temporarily re-enable the deprecated APIs, enable the datasourceLegacyIdApi feature flag.
Both the deprecated APIs and the feature toggle will be removed in a future release.
In Grafana 13, support for the Image Renderer plugin is removed.
You run the Image Renderer as a Grafana plugin. After upgrading, the plugin no longer works for rendering screenshots or scheduled reports.
Deploy the image renderer as a separate service alongside Grafana. For setup instructions, refer to Set up image rendering.
The Image Renderer previously authenticated with Grafana using opaque tokens stored in the database when generating screenshots and PDFs. Grafana v13.0 enables the renderAuthJWT feature toggle by default, which switches authentication to stateless JSON Web Tokens (JWTs) that don't depend on the database.
After upgrading to Grafana v13.0, if you use the Image Renderer, you must set a [rendering]renderer_token in your Grafana configuration file to a value that isn't empty or the default value (-), and configure the Image Renderer with the same token value. Restart your Grafana instance for the changes to take effect.
For more information, refer to the Image Renderer security configuration documentation.
After upgrading to Grafana v13.0, to revert to opaque token authentication, disable the feature toggle in your Grafana configuration file:
[feature_toggles]
renderAuthJWT = false
Restart your Grafana instance for the changes to take effect.
Grafana v13.0 automatically migrates folders and dashboards from the legacy SQL database to unified storage on startup.
The migration runs once and is tracked in the unifiedstorage_migration_log table.
After the migration completes, the following legacy tables are deprecated:
dashboarddashboard_acldashboard_provisioningdashboard_versiondashboard_taglibrary_element_connectionfolderThese tables will be removed in a future release.
If you downgrade to an earlier Grafana version after the migration, the older version reads the stale legacy tables and doesn't reflect changes made in unified storage. To roll back, restore from the database backup you took before upgrading.
If you downgrade and then upgrade again without restoring a backup, any folders or dashboards created or modified during the downgrade aren't migrated automatically. If a backup isn't available, contact Grafana support for assistance.
If you use SQLite, the migration might fail with database is locked or database table is locked errors due to lock contention.
Grafana automatically retries using the Parquet buffer, but if errors persist, increase migration_cache_size_kb or enable migration_parquet_buffer in the [unified_storage] section of your configuration file:
| Setting | Description | Default |
|---|---|---|
migration_cache_size_kb | SQLite page cache size during migration. | 1000000 (~1 GB) |
migration_parquet_buffer | Stage data through a temporary Parquet file to separate read and write phases, avoiding lock contention. | false |
grafana-cli and grafana-server commandsThe grafana-cli and grafana-server commands, deprecated since Grafana v10.0, are removed in Grafana v13.0.
Update any scripts, systemd units, Docker entrypoints, CI pipelines, or other automation to use grafana cli and grafana server instead.
Several legacy Alertmanager configuration API endpoints are removed or restricted in Grafana v13.0:
DELETE /api/alertmanager/grafana/config/api/v1/alerts is removed.POST /api/alertmanager/grafana/config/api/v1/receivers/test is removed.GET /api/alertmanager/grafana/config/api/v1/alerts is restricted to admin users.GET /api/alertmanager/grafana/config/history is restricted to admin users.POST /api/alertmanager/grafana/config/history/{id}/_activate is restricted to admin users.You call any of these endpoints in automation scripts, Terraform providers, or custom tooling.
Migrate to the Kubernetes-style resource APIs under notifications.alerting.grafana.app/v1beta1:
| Resource | API path |
|---|---|
| Receivers | /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers |
| Notification policies | /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees |
| Templates | /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups |
| Mute timings | /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals |
| Inhibition rules | /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules |
| Receiver testing | /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{uid}/test |
You use the GET /api/alertmanager/grafana/api/v2/status endpoint and rely on the alert.notifications:read permission to access it.
The GET /api/alertmanager/grafana/api/v2/status endpoint previously required the legacy alert.notifications:read permission. It now requires a dedicated alert.notifications.system-status:read permission. This new permission is included in the fixed:alerting.notifications:writer role, which is granted to Admin users by default.
If you have custom roles that need access to this endpoint, add the alert.notifications.system-status:read action to those roles. Admin users are unaffected as they receive this permission automatically through the built-in alerting notifications writer role.