Folders

Organize dashboards and manage permissions with folders

Folders provide a hierarchical structure for organizing dashboards, library panels, and other resources. They also serve as the primary mechanism for managing access permissions.

What are Folders?

Folders in Grafana organize resources and control access:

• Hierarchical organization: Group related dashboards together
• Permission boundary: Control who can view, edit, or admin resources
• Search scope: Filter searches by folder
• Resource container: Store dashboards, library panels, alert rules

Folders can contain sub-folders, creating a tree structure for complex organizations.

Creating Folders

Via the UI

1. Navigate to Dashboards
2. Click New → New folder
3. Enter a folder name
4. Optionally set a parent folder (for sub-folders)
5. Configure initial permissions
6. Click Create

Via the API

POST Create Folder

curl -X POST \
  'http://localhost:3000/api/folders' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "name": "my-team-folder"
    },
    "spec": {
      "title": "My Team",
      "description": "Dashboards for the platform team"
    }
  }'

curl -X POST \
  'http://localhost:3000/api/folders' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "name": "production-dashboards"
    },
    "spec": {
      "title": "Production",
      "parent": "my-team-folder"
    }
  }'

TypeScript Interface

interface Folder {
  metadata: {
    name: string;              // Unique identifier (UID)
    namespace?: string;
    labels?: Record<string, string>;
    annotations?: Record<string, string>;
    resourceVersion?: string;
    creationTimestamp?: string;
  };
  spec: {
    title: string;             // Display name
    description?: string;
    parent?: string;           // Parent folder UID
  };
}

Managing Folders

Get Folder Information

GET Folder by UID

curl 'http://localhost:3000/api/folders/{uid}'

curl 'http://localhost:3000/api/folders/{uid}/parents'

curl 'http://localhost:3000/api/folders'

import { useGetFolderQuery, useGetFolderParentsQuery } from 'app/api/clients/folder/v1beta1';

// Get folder details
const { data: folder } = useGetFolderQuery({ name: 'folder-uid' });

// Get parent hierarchy
const { data: parents } = useGetFolderParentsQuery({ name: 'folder-uid' });

Update Folder

Update folder title, description, or parent:

PUT Update Folder

curl -X PUT \
  'http://localhost:3000/api/folders/{uid}' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "name": "folder-uid",
      "resourceVersion": "123"  // Required for optimistic locking
    },
    "spec": {
      "title": "Updated Title",
      "description": "Updated description"
    }
  }'

import { useUpdateFolderMutation } from 'app/api/clients/folder/v1beta1';

const [updateFolder] = useUpdateFolderMutation();

await updateFolder({
  name: 'folder-uid',
  folder: {
    metadata: {
      name: 'folder-uid',
      resourceVersion: currentVersion
    },
    spec: {
      title: 'Updated Title',
      description: 'New description'
    }
  }
});

Delete Folder

Deleting a folder also deletes its contents:

Deleting a folder removes all dashboards, library panels, and alert rules it contains. This action cannot be undone.

curl -X DELETE 'http://localhost:3000/api/folders/{uid}'

Before deleting, check folder contents:

import { useGetAffectedItemsQuery } from 'app/api/clients/folder/v1beta1';

const { data: counts } = useGetAffectedItemsQuery({
  folderUIDs: ['folder-uid'],
  dashboardUIDs: []
});

console.log(`Will delete:`);
console.log(`  ${counts.folders} folders`);
console.log(`  ${counts.dashboards} dashboards`);
console.log(`  ${counts.library_elements} library panels`);
console.log(`  ${counts.alertrules} alert rules`);

Folder Counts Interface

interface DescendantCount {
  folders: number;
  dashboards: number;
  library_elements: number;
  alertrules: number;
}

Moving Dashboards Between Folders

Move Single Dashboard

Update the dashboard’s folderUid property:

interface DashboardMeta {
  folderUid?: string;
  folderTitle?: string;
  // ... other meta properties
}

// When saving a dashboard
const dashboard = {
  // ... dashboard model
  meta: {
    folderUid: 'target-folder-uid'
  }
};

Move Multiple Dashboards

Move Dashboard API

curl -X POST \
  'http://localhost:3000/api/dashboards/db' \
  -H 'Content-Type: application/json' \
  -d '{
    "dashboard": { /* dashboard JSON */ },
    "folderUid": "target-folder-uid",
    "overwrite": true
  }'

Folder Permissions

Folders are the primary unit for permission management in Grafana.

Permission Levels

• View: Read-only access to dashboards and library panels
• Edit: Create and modify dashboards and library panels
• Admin: Manage folder settings, permissions, and deletion

Permission Inheritance

Resources inherit permissions from their folder:

• Dashboards in a folder inherit the folder’s permissions
• Library panels inherit permissions from their folder
• Alert rules inherit permissions from their folder
• Sub-folders inherit default permissions (can be overridden)

Users need at least View permission on a folder to see dashboards within it.

Setting Permissions

Permissions can be assigned to:

• Users: Individual user accounts
• Teams: Groups of users
• Roles: Organization roles (Viewer, Editor, Admin)

Via UI:

1. Go to folder settings
2. Navigate to Permissions tab
3. Add users, teams, or roles
4. Set permission level
5. Save changes

Via API:

curl -X POST \
  'http://localhost:3000/api/folders/{uid}/permissions' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "role": "Viewer",
        "permission": 1
      },
      {
        "teamId": 2,
        "permission": 2
      },
      {
        "userId": 5,
        "permission": 4
      }
    ]
  }'

Permission values:

• 1: View
• 2: Edit
• 4: Admin

Default Permissions

New folders inherit default organization permissions:

• Viewers role: View permission
• Editors role: Edit permission
• Admins role: Admin permission

You can override these defaults when creating or updating folders.

Folder Hierarchy

Parent-Child Relationships

Folders can be nested to create hierarchies:

Platform Team/
├── Production/
│   ├── API Dashboards/
│   └── Database Dashboards/
└── Staging/
    └── Test Dashboards/

Navigation

Breadcrumbs show the folder path:

import { useGetFolderParentsQuery } from 'app/api/clients/folder/v1beta1';

const { data: parents } = useGetFolderParentsQuery({ name: 'folder-uid' });

// Renders breadcrumb: Home > Platform Team > Production > API Dashboards
const breadcrumb = parents?.items.map(p => p.spec.title).join(' > ');

Moving Folders

Change a folder’s parent by updating its parent field:

import { useUpdateFolderMutation } from 'app/api/clients/folder/v1beta1';

const [updateFolder] = useUpdateFolderMutation();

await updateFolder({
  name: 'child-folder-uid',
  folder: {
    metadata: { name: 'child-folder-uid' },
    spec: {
      title: 'Child Folder',
      parent: 'new-parent-uid'  // Move to different parent
    }
  }
});

Searching Within Folders

Filter search results by folder:

import { getGrafanaSearcher } from 'app/features/search/service/searcher';

const searcher = getGrafanaSearcher();

// Search within specific folders
const results = await searcher.search({
  query: 'cpu usage',
  kind: ['dashboard'],
  location: 'folder-uid'  // Limit to this folder
});

Search API

Search in Folder

curl 'http://localhost:3000/api/search?folderIds=1&query=cpu'

curl 'http://localhost:3000/api/search?folderIds=1&type=dash-db'

Virtual Folders

Grafana provides special virtual folders:

• General: Default folder for dashboards without a folder
• Recent: Recently viewed dashboards
• Starred: User-starred dashboards

These cannot be deleted or have permissions modified.

API Reference Summary

Create Folder

POST /api/folders

GET /api/folders/{uid}

PUT /api/folders/{uid}

DELETE /api/folders/{uid}

GET /api/folders/{uid}/parents

GET /api/folders/{uid}/counts

POST /api/folders/{uid}/permissions

GET /api/folders/{uid}/permissions

Best Practices

Organize by Team and Environment

Structure folders to match your organization:

SRE/
├── Production/
├── Staging/
└── Development/

Data Engineering/
├── Pipelines/
└── Quality/

This makes ownership and access control clear.

Use Descriptive Names

• Avoid generic names like Folder 1 or Test
• Include scope: API Production Dashboards
• Be consistent across similar folders

Set Permissions at Folder Level

Rather than setting permissions on individual dashboards:

1. Create folders with appropriate permissions
2. Place dashboards in correctly-permissioned folders
3. Use teams for group-based access control

This is easier to maintain than per-dashboard permissions.

Limit Nesting Depth

While Grafana supports deep hierarchies, keep it simple:

• Good: 2-3 levels (Team → Environment → Service)
• Too deep: 5+ levels become hard to navigate
• Use dashboard tags for additional categorization

Document Folder Purpose

Use the description field to explain:

• What dashboards belong here
• Who owns this folder
• Any special access considerations

This helps teams navigate large Grafana instances.

Audit Before Deletion

Always check folder contents before deleting:

const { data: counts } = useGetAffectedItemsQuery({
  folderUIDs: ['folder-to-delete'],
  dashboardUIDs: []
});

if (counts.dashboards > 0) {
  console.warn(`Warning: Deleting ${counts.dashboards} dashboards`);
}

Related Topics

Dashboards

Create and manage dashboards within folders

Library Panels

Store reusable panels in folders

Permissions

Detailed permission model documentation

Teams

Manage team-based folder access