Grafana

1. Overview

Grafana is a leading open-source platform for monitoring, data visualization, and observability. It allows you to query, visualize, alert on, and explore your metrics, logs, and traces no matter where they are stored.

With the GoInsight Grafana node, you can seamlessly integrate Grafana administration into your automated workflows. This allows you to programmatically manage key resources within your Grafana instance, including:

• Dashboard Management: Create, retrieve, update, and delete dashboards.
• Team and User Administration: Build and manage teams, add or remove members, and handle user accounts.
• Data Retrieval: Fetch lists of dashboards, teams, and users to use in subsequent workflow steps.

2. Prerequisites

Before using this node, you must have a valid Grafana account with the necessary permissions to generate API keys. Depending on the operations you wish to perform, the API key may require Viewer, Editor, or Admin privileges.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following resources: Dashboard, Team, Team Member, and User.

Operation Details

Create a Dashboard

Creates a dashboard. Use Overwrite to update existing ones.

When to use:

• Provision a dashboard programmatically.
• Save a dashboard from a Grafana JSON model.
• Update an existing dashboard by reusing its uid and setting Overwrite to true.

Key points:

• Dashboard must include at least title; set id and uid to null for new dashboards.
• Keep Overwrite false unless you want to replace a dashboard with the same uid.
• Grafana commonly returns 412 when the uid already exists and Overwrite is false.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry. Overwrite=true may replace an existing dashboard and overwrite prior changes.

Next:

Use Dashboard.uid with Get a Dashboard to verify the saved dashboard, or with Update a Dashboard to modify it later. Combine BASE_URL and Dashboard.url to build a shareable link.

Input Parameters:

• Dashboard: The complete dashboard definition object. Required structure: title (string, required), id (set to null for new dashboards), uid (set to null for new dashboards or provide an existing uid when overwriting). Common optional fields: tags (array of strings), timezone (string: "browser" or "utc"), schemaVersion (number, typically 16), panels (array of panel objects), time (object with from/to), and refresh (string such as "5s" or "1m"). Each panel typically includes id (number), type (string), title (string), gridPos (object with x/y/w/h), and targets (array of query objects). For non-Grafana users: schemaVersion is the dashboard format version, gridPos controls panel position and size, and targets contains the actual data queries. If building this object manually is too complex, export a dashboard JSON model from Grafana and edit the fields you need.

Options:

• Overwrite: Whether to overwrite an existing dashboard with the same UID. Set to true when updating an existing dashboard; set to false to avoid accidental overwrites. Defaults to false.

Output:

• Dashboard (object): The created or updated dashboard info returned by Grafana API. Fields: id (number, Grafana internal dashboard ID), uid (string, dashboard identifier for later API calls), url (string, relative dashboard path such as /d/{uid}/{slug}), status (string, typically success), version (number, dashboard version after save), and slug (string, URL-friendly title). Returns empty object {} if operation failed.
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a Dashboard

Deletes a dashboard.

When to use:

• Remove a dashboard that is no longer needed.
• Clean up obsolete dashboards after replacement.
• Execute a controlled dashboard decommission workflow by UID.

Key points:

• Uid is required and can be found in the dashboard URL, Dashboard Settings > General, or by using Get Many Dashboards.
• On success, DeletedDashboard contains the response fields and deleted uid.
• This action targets one dashboard only and does not delete folders.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry. Deleting a dashboard is destructive; recovery is not guaranteed and depends on your Grafana environment.

Next:

Use DeletedDashboard.uid with Get a Dashboard to confirm the dashboard no longer resolves. Use DeletedDashboard.title and DeletedDashboard.id in logs or change records.

Input Parameters:

• Uid: The unique identifier (UID) of the dashboard to delete. You can find it in the dashboard URL as /d/{UID}/..., in Dashboard Settings > General > UID, or by using the Get Many Dashboards action. Grafana dashboard UIDs are strings up to 40 characters. Example: "cIBgcSjkk"

Output:

• DeletedDashboard (object): Deleted dashboard result returned by Grafana, wrapped in a single object. Contains title (string), message (string), id (number), and uid (string).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Dashboards

Searches Grafana dashboards by title with pagination (GET /api/search, type dash-db).

When to use:

• Discover dashboard uid before Get a Dashboard, Update a Dashboard, or Delete a Dashboard.
• List dashboards in a folder or filter by title keyword.
• Page through large dashboard lists with PerPage and Page.

Key points:

• On success, Dashboards.dashboards is the raw array from Grafana search.
• uid and title are the usual keys for follow-up dashboard APIs.
• per_page is limited to 1-1000; page must be >= 1.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Dashboards.dashboards[].uid with Get a Dashboard, Update a Dashboard, or Delete a Dashboard.

Options:

• Query: Optional text to filter dashboards by title. Example: metrics
• PerPage: Number of dashboards per page (1-1000). Defaults to 1000.
• Page: Page number to retrieve. Defaults to 1.

Output:

• Dashboards (object): Dashboard search hits from Grafana, wrapped in one object. Contains dashboards (array). Each item may include id (number), uid (string), title (string), uri (string), url (string), slug (string), type (string), tags (array), isStarred (boolean), folderId (number), folderUid (string), folderTitle (string), folderUrl (string).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get a Dashboard

Gets a dashboard by UID.

When to use:

• Read a dashboard definition before updating, deleting, or auditing it.
• Retrieve dashboard title, tags, panels, and metadata for workflow steps.
• Verify that a dashboard UID exists and points to the expected dashboard.

Key points:

• Uid is required and can be found in the dashboard URL, Dashboard Settings > General, or by using Get Many Dashboards.
• On success, Dashboard.dashboard contains the dashboard model and Dashboard.meta contains url and slug metadata.
• Grafana dashboard UIDs are strings up to 40 characters; example: cIBgcSjkk.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Dashboard.dashboard.uid with Update a Dashboard or Delete a Dashboard. Use Dashboard.dashboard.title and Dashboard.meta.url in approval or reporting steps.

Input Parameters:

• Uid: The unique identifier (UID) of the dashboard to retrieve. You can find it in the dashboard URL as /d/{UID}/..., in Dashboard Settings > General > UID, or by using the Get Many Dashboards action. Grafana dashboard UIDs are strings up to 40 characters. Example: "cIBgcSjkk"

Output:

• Dashboard (object): Dashboard data retrieved from Grafana. Contains dashboard (object, the dashboard definition with fields such as id, uid, title, tags, schemaVersion, version, refresh, and panels) and meta (object, dashboard metadata such as isStarred, url, slug, folderId, and folderUid when present).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Update a Dashboard

DESTRUCTIVE: overwrite true fully replaces the dashboard; omitted fields reset to defaults and are not recoverable. Always start from Get a Dashboard output.

When to use:

• Save edits after pulling the current model with Get a Dashboard.
• Change title, tags, panels, refresh, or timezone in one write.

Key points:

• Input Dashboard is the full save payload; output Dashboard is save metadata (uid, url, version, status), not full panels.
• RequestExample uses one simplified panel; real dashboards usually have many panels from Get a Dashboard.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Get Many Dashboards or Get a Dashboard for uid and the full model first. After success, use Dashboard.url or Dashboard.uid for follow-up.

Input Parameters:

• Dashboard: DESTRUCTIVE (overwrite true): this payload replaces the entire dashboard; omitted keys can revert to defaults. REQUIRED: uid (string) from Get a Dashboard or Get Many Dashboards; title (string). STRONGLY RECOMMENDED: start from the complete JSON returned by Get a Dashboard. OPTIONAL: tags (array), timezone (string), refresh (string), panels (array), schemaVersion (number), version (number).

Output:

• Dashboard (object): Grafana POST /api/dashboards/db response JSON on success. Core fields often include: id (number), uid (string), url (string path), slug (string), status (string, often success), version (number), folderUid (string, optional). Grafana may return additional keys. Empty {} on validation failure or when the response body was not a JSON object; check ErrorMessage.
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Create a Team

Creates a Grafana team by name and email. If the name already exists, returns that team without creating a duplicate.

When to use:

• Provision a team before Add a Team Member or Get Many Team Members.
• Ensure a stable team record when workflows may retry.

Key points:

• Calls GET /api/teams/search by name, then POST /api/teams when no exact name match.
• Team may include teamId or id from Grafana; use the numeric id for team-scoped APIs.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Team.teamId or Team.id with Get Many Team Members, Add a Team Member, or Update a Team.

Input Parameters:

• Name: Team name to create. Should be unique in the org for clarity. Example: dev-team
• Email: Team contact email for notifications and identification. Format: name@domain. Example: dev-team@company.com

Output:

• Team (object): Created or existing team. Common fields: teamId (number, use for team APIs), name (string), email (string), orgId (number), created (string, ISO 8601), updated (string). Search results may expose id instead of teamId; both refer to the team primary key.
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a Team

Deletes a team from Grafana.

When to use:

• Remove a team that is no longer needed.
• Clean up obsolete access structures after a team is retired.
• Execute a controlled team decommission workflow by ID.

Key points:

• TeamId is required and can be obtained from Get Many Teams or Create a Team.
• On success, DeletedTeam contains the response message and deleted teamId.
• Deleting a team removes the team container, not the user accounts themselves.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry. Deleting a team is destructive and may immediately remove dashboard or permission access inherited from that team.

Next:

Use DeletedTeam.teamId with Get a Team to confirm the team no longer resolves. Use DeletedTeam.teamId with Get Many Team Members before deletion planning or in audit records.

Input Parameters:

• TeamId: The ID of the team to delete. Team IDs can be obtained from the Get Many Teams action or the Create a Team action. Team IDs are positive integers starting from 1. Example: 123

Output:

• DeletedTeam (object): Deleted team result returned by Grafana, wrapped in a single object. Contains message (string, for example "Team deleted") and teamId (number).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Teams

Gets teams from Grafana with optional filtering and pagination.

When to use:

• Retrieve teams for reporting, routing, or audits.
• Find a specific team by exact name or fuzzy query.
• Page through teams when building multi-step workflows.

Key points:

• If Name is provided, Query, Sort, Page, and PerPage are ignored and Grafana performs an exact-name lookup.
• If Name is empty, Query performs substring matching and Sort controls the returned order.
• Teams includes totalCount, teams, page, and perPage so you can detect whether more pages remain.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Teams.teams[].id with Get a Team to inspect one team in detail, or with Delete a Team if you need to remove it. Use Teams.totalCount and Teams.perPage to plan additional page requests.

Options:

• Name: Exact team name to search for. NOTE: If Name is provided, Query/Page/PerPage/Sort parameters will be ignored. Use this for precise lookup. Example: "Engineering Team"
• Query: Fuzzy search string to filter teams by name (substring match). NOTE: Only effective when Name is empty. Supports partial matching. Example: "dev" will match "Development Team", "DevOps Team"
• Sort: Sort order for the team list. Supported options:
• name-asc / name-desc: Sort by team name (alphabetical)
• email-asc / email-desc: Sort by team email
• memberCount-asc / memberCount-desc: Sort by number of team members

Default: name-asc. Example: "memberCount-desc" (teams with most members first)

• PerPage: Number of teams to return per page. Must be between 1 and 1000. Default: 1000. Example: 1000
• Page: Page number to retrieve. Starts at 1. Default: 1. Example: 1

Output:

• Teams (object): Object containing teams and pagination metadata retrieved from Grafana. Structure: totalCount (number, total teams matching the request), teams (array of team objects), page (number, current page), and perPage (number, page size). Each item in teams may include id (number), name (string), email (string), memberCount (number), orgId (number), avatarUrl (string), and permission (number). Use totalCount with perPage to estimate whether more pages remain.
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get a Team

Gets a specific team from Grafana by its unique ID.

When to use:

• Fetch full details of a specific team
• Verify if a team exists before updating
• Look up a team when you already have its ID

Key points:

• TeamId must be a positive integer
• Returns a detailed team object including metadata (memberCount, permission)

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use the returned Team.id with Update a Team to modify details, or Delete a Team to remove it.

Input Parameters:

• TeamId: The unique identifier of the team to retrieve. You can obtain Team IDs by:
• Calling the List Teams action (grafana_list_teams)
• Checking the Grafana UI: Settings → Teams → Click a team → ID in URL (e.g., /org/teams/edit/5)

Example: 5

Output:

• Team (object): Team data retrieved from Grafana. Contains the following core fields:
• id (number): Team unique identifier
• name (string): Team name
• email (string): Team contact email
• orgId (number): Organization ID
• memberCount (number): Number of team members
• permission (number): Permission level (0=View, 1=Edit, 2=Admin)
• created (string): Creation timestamp (ISO 8601)
• updated (string): Last update timestamp (ISO 8601)

Example: {"id": 5, "name": "Engineering Team", "email": "engineering@company.com", "memberCount": 12}

• OriginalStatusCode (number): The original HTTP status code returned by the Grafana API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• 0: Network error (timeout/connection refused)
• 200: Team retrieved successfully
• 401: Invalid API key
• 403: Permission denied
• 404: Team not found
• 5xx: Grafana server error
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Update a Team

Updates a team in Grafana.

When to use:

• Modify the name or email of an existing team.
• Keep team members and permissions intact while changing team details.
• Apply a controlled metadata update after reading the current team values.

Key points:

• Both Name and Email are required parameters.
• This endpoint uses full replacement (PUT), so changing one field still requires the current value of the other field.
• Grafana only returns a success message here; call Get a Team to verify the updated values.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry. Update Strategy: this is a full replacement (PUT) operation, not a partial patch.

Next:

Use the same TeamId with Get a Team to verify the updated Name and Email. Use Team.message only as a save confirmation, not as the source of team details.

Input Parameters:

• TeamId: The unique identifier of the team to update. You can obtain Team IDs by:
• Calling the List Teams action (grafana_list_teams)
• Checking the Grafana UI: Settings → Teams → Click a team → ID in URL (e.g., /org/teams/edit/5)

Example: 5

• Name: The new name of the team. This is a full replacement (PUT) operation, so you must also provide the current Email value even if you only want to change Name. Call Get a Team first if you need to read the current values. Example: "Engineering Team"
• Email: The new email of the team. This is a full replacement (PUT) operation, so you must also provide the current Name value even if you only want to change Email. Call Get a Team first if you need to read the current values. Example: "engineering@company.com"

Output:

• Team (object): Object containing the API response after the update. Grafana's update response only contains a success message, not the full team object. Includes: message (string), for example "Team updated". To verify the updated Name and Email, call Get a Team with the same TeamId. Example: {"message": "Team updated"}
• OriginalStatusCode (number): The original HTTP status code returned by the Grafana API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Add a Team Member

Adds a user to a team.

When to use:

• Grant team-based access to a user.
• Add a known user to an existing team after checking membership.
• Automate team onboarding after selecting a team and user ID.

Key points:

• TeamId is required and can be obtained from Get Many Teams or Create a Team.
• UserId is required and can be obtained from Get Many Users.
• On success, TeamMember contains the response message plus the teamId and userId used for the addition.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry. Adding a user to a team may immediately grant access to dashboards and folders assigned to that team.

Next:

Use TeamMember.teamId with Get Many Team Members to verify the membership list. Use TeamMember.teamId and TeamMember.userId with Remove a Team Member to roll back the access change.

Input Parameters:

• TeamId: The ID of the team to add the user to. Team IDs can be obtained from the Get Many Teams action or the Create a Team action. Team IDs are positive integers starting from 1. Example: 1
• UserId: The ID of the user to add to the team. User IDs can be obtained from the Get Many Users action. User IDs are positive integers. Example: 2

Output:

• TeamMember (object): Team membership result returned by Grafana, wrapped in a single object. Contains message (string, for example "Member added to Team"), teamId (number), and userId (number).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Team Members

Gets all members of a Grafana team.

When to use:

• Review current team membership before changing access.
• Collect userId, login, email, and permission for downstream workflow decisions.
• Verify membership before Add a Team Member or Remove a Team Member.

Key points:

• TeamId is required, must be greater than 0, and can be obtained from Get Many Teams or Create a Team.
• On success, Members.members is the raw member array returned by Grafana.
• This endpoint returns one response without pagination parameters.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Members.members[].userId with the same TeamId in Remove a Team Member to remove a user. Compare Members.members[].userId with Get Many Users, then pass the missing userId and the same TeamId to Add a Team Member.

Input Parameters:

• TeamId: The ID of the team to get members for. Team IDs can be obtained from the Get Many Teams action or the Create a Team action. Team IDs are positive integers starting from 1. Example: 1

Output:

• Members (object): Team members retrieved from Grafana, wrapped in a single object. Contains members (array of raw team member objects). Each member object may include orgId (number), teamId (number), userId (number), email (string), login (string), avatarUrl (string), and permission (number, where 0 = Member and 4 = Admin).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Remove a Team Member

Removes a user from a Grafana team by team ID and user ID.

When to use:

• Remove a member who no longer needs access to a team's dashboards (e.g., contractor project ends).
• Clean up team membership after a user leaves a project or department.
• Revoke team-level permissions without deleting the user's Grafana account.

Key points:

• TeamId: obtain from Get Many Teams; UserId: obtain from Get Team Members (userId field).
• Removing a member does not delete the user from Grafana, only removes team membership.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

This action permanently removes the user from the team and cannot be undone. The user must be re-added manually.

Next:

Use Get Team Members to verify the member has been removed.

Input Parameters:

• TeamId: The ID of the team to remove the member from. Obtain this ID from Get Many Teams or Search Teams action. Example: 1
• UserId: The ID of the user to remove from the team. Obtain this ID from Get Team Members action (returns members with userId field). Example: 42

Output:

• RemovedTeamMember (object): Confirmation object for the removed member. Contains teamId and userId. Returns empty object {} if operation failed.
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a User

Deletes a user from Grafana.

When to use:

• Remove a user from the current or a specific organization.
• Clean up access after offboarding or account retirement.
• Execute a controlled user deprovisioning workflow by user ID.

Key points:

• UserId is required and can be obtained from Get Many Users.
• OrgId is optional; use 0 for the current org context or a positive org ID.
• On success, DeletedUser contains the response message, userId, and orgId.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry. Deleting a user is destructive and may remove access, preferences, and ownership tied to that user in Grafana.

Next:

Use DeletedUser.userId with Get Many Users to verify the user is no longer returned for the target org context. Record DeletedUser.userId and DeletedUser.orgId in audit logs.

Input Parameters:

• UserId: The ID of the user to delete from the organization. User IDs can be obtained from the Get Many Users action. User IDs are positive integers. Example: 42

Options:

• OrgId: The ID of the organization to target. Use 0 to delete the user from the current organization context, or pass a positive organization ID to target a specific org. Example: 1

Output:

• DeletedUser (object): Deleted user result returned by Grafana, wrapped in a single object. Contains message (string), userId (number), and orgId (number, where 0 means current organization context).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Users

Lists org users from Grafana with optional query and pagination (GET /api/org/users).

When to use:

• Inspect membership or resolve userId before Update a User, Delete a User, or team member changes.
• Cross-check with Get Many Team Members for Add/Remove a Team Member.

Key points:

• Query: substring match on login, name, email; PerPage 1-1000; Page from 1; request uses perpage/page.
• Users holds users, page, per_page, count, has_more (true if count equals per_page, heuristic). Roles: Admin, Editor, Viewer.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use Users.users[].userId with Update or Delete a User; align with Get Many Team Members. If Users.has_more, retry with Page+1.

Options:

• Query: Optional search keyword to fuzzy match users by login, name, or email (case-insensitive). Supports partial string matching, wildcards are not supported. Examples: admin, @gmail.com, John. Leave empty to return users paginated.
• PerPage: Number of users to return per page. Default is 1000, maximum is 1000, used to control the amount of returned data. Example: 100
• Page: Page number, starting from 1. Used in conjunction with PerPage for pagination. Example: 1

Output:

• Users (object): Organization users from Grafana. Contains users (array): raw org user objects; page (number): requested page; per_page (number): page size; count (number): users in this response; has_more (boolean): true when count equals per_page (may indicate another page). Each user may include orgId (number), userId (number), email (string), name (string), login (string), role (string: Admin full access, Editor can edit, Viewer read-only), lastSeenAt (string, optional), lastSeenAtAge (string, optional).
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Update a User

Updates a user's role in a Grafana organization.

When to use:

• Change a user's permission level within an organization.
• Promote a Viewer to Editor or Admin after onboarding.
• Demote a user's role when reducing access.

Key points:

• Role must be one of: Viewer, Editor, Admin (case-sensitive).
• OrgId defaults to the current organization when set to 0 or omitted.
• This action only updates the role; other user attributes are not affected.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success.

StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Next:

Use User.userId with Get a User to verify the updated role.

Input Parameters:

• UserId: The ID of the user to update in the organization.
• Role: The new role for the user. Accepted values: Viewer, Editor, Admin.

Options:

• OrgId: The ID of the organization to update the user in. Uses the current organization if set to 0 or omitted.

Output:

• User (object): Confirmation object for the updated user. Contains userId and the new role. Returns empty object {} if operation failed.
• OriginalStatusCode (number): The original HTTP status code returned by Grafana API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

5. Example Usage

This section will guide you through creating a simple workflow to create a new team in your Grafana instance.

The workflow will consist of three nodes: Start -> Grafana: Create a Team -> Answer.

1. Add the Grafana Node

• On the workflow canvas, click the + button to add a new node.
• In the panel that appears, select the "Tools" tab.
• Find and select "Grafana" from the list of tools.
• From the list of supported operations for Grafana, click on "Create a Team" to add the node to the canvas.

2. Configure the Node

• Click on the newly added "Create a Team" node to open its configuration panel on the right.
• Credentials: Find the credentials field at the top. Click the dropdown menu and select your pre-configured Grafana credential.
• Parameters: Fill in the required input parameters for the operation.
  • Name: Enter the desired name for your new team, for example, Marketing Analytics.
  • Email: Provide a contact or group email for the team, such as marketing-analytics@example.com.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the team was created successfully.

After completing these steps, your workflow is fully configured. When you run it, a new team will be created in your Grafana organization.

6. FAQs

Q: Why am I getting a 401 Unauthorized or 403 Forbidden error?

A: This typically indicates an issue with your API key or its permissions. Please check the following:

• Valid API Key: Ensure the API key used in your credential is correct and has not expired or been revoked in Grafana.
• Correct Role: The API key must have a role with sufficient permissions for the operation you are trying to perform (e.g., you need an Admin role to delete users or teams).
• Instance URL: Verify that the Grafana URL in your credential configuration is correct and accessible.

Q: How do I find the TeamId or UserId needed for some operations?

A: You can typically find these IDs in a couple of ways:

• Grafana UI: When you navigate to a team's or user's settings page in the Grafana web interface, the ID is often visible in the URL.
• GoInsight Workflow: Use the Get Many Teams or Get Many Users operations in a preceding step of your workflow. These operations will return a list of objects, each containing the name and ID, which you can then use as input for other nodes.

Q: What is the format for the Dashboard object when creating or updating a dashboard?

A: The Dashboard parameter expects a JSON object that represents the complete Grafana dashboard model. This includes properties like title, panels, templating, time, etc. The easiest way to get a valid structure is to export an existing dashboard from the Grafana UI as JSON and use that as a template. For detailed specifications, refer to the official Grafana documentation on the dashboard JSON model.

7. Official Documentation

For more in-depth information about the Grafana API and its capabilities, please refer to the Grafana Official API Documentation.