Documentation for automated readers A curated documentation index is available at: https://grafana.com/llms.txt
A complete documentation index is available at: https://grafana.com/llms-full.txt These indexes can help with page discovery before fetching individual documents.
This page is also available in Markdown, which may be easier for automated readers
and AI tools to parse than HTML. The Markdown version is available at
https://grafana.com/docs/grafana-cloud/platform/workflows/reference/api.md, or by sending
Accept: text/markdown to https://grafana.com/docs/grafana-cloud/platform/workflows/reference/api/. For broader
documentation discovery, the curated index is available at https://grafana.com/llms.txt
and the complete index is available at https://grafana.com/llms-full.txt.
Grafana Workflows is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
This page lists the endpoints, parameters, fields, and error codes of the Grafana Workflows API.
For step-by-step examples, refer to Use the API.
Caution
The run endpoints might change during public preview.
Endpoints
Every request needs an Authorization: Bearer <SERVICE_ACCOUNT_TOKEN> header.
Requests with a body also need a Content-Type: application/json header, except for PATCH requests, which use application/merge-patch+json.
Definitions endpoints
These endpoints create, read, update, and delete workflows.
Their paths start with /apis/workflows.ext.grafana.app/v1alpha1/namespaces/<NAMESPACE>/definitions, where NAMESPACE is stacks-<STACK_ID>.
Method and path
Description
DELETE .../definitions/<NAME>
Deletes a workflow.
GET .../definitions
Lists workflows.
GET .../definitions/<NAME>
Gets one workflow.
PATCH .../definitions/<NAME>
Changes the fields in the request body and leaves the other fields unchanged.
POST .../definitions
Creates a workflow. Add ?dryRun=All to check the definition without saving it.
PUT .../definitions/<NAME>
Replaces a workflow. The body must include the current metadata.resourceVersion. Add ?dryRun=All to check the definition without saving it.
NAME is the workflow’s metadata.name.
Run endpoints
These endpoints run workflows and return results.
Their paths start with /api/plugins/grafana-workflows-app/resources/api/v1.
Method and path
Description
GET .../runs
Lists runs across all workflows, newest first. Accepts the list runs parameters.
Runs the definition in the request body. You don’t need to save the workflow or turn it on. Refer to Trigger request body.
DEFINITION_UID is the workflow’s metadata.uid.
The run and trigger endpoints return the run’s instance_id and execution_id.
Running a workflow requires the Workflows Writer role.
Request bodies
The run and trigger endpoints accept the following request bodies.
Run request body
The body is optional.
Field
Type
Description
inputs
Object
Optional: The values that steps read as inputs.*. For a workflow that normally starts from an event, put the event’s fields in inputs.data.
Trigger request body
Field
Type
Description
definition
Object
The complete workflow definition to run. Include metadata.uid to link the run to a saved workflow’s run history.
event_data
Object
Optional: An event in CloudEvents format. Steps read the fields under event_data.data as inputs.data.*.
List runs parameters
Both list runs endpoints accept the following query parameters.
All of them are optional.
Parameter
Description
after
A cursor for the next page. Use the next_cursor value from the previous response.
count
The number of runs to return. The default is 25, and the maximum is 100.
created_after
Return only runs created at or after this time. Use the RFC 3339 date and time format, for example, 2026-09-01T00:00:00Z.
created_before
Return only runs created at or before this time. Use the RFC 3339 format.
status
Return only runs with this status: active, completed, or failed.
Run fields
Runs in list and run responses include the following fields.
Field
Description
completed_at
When the run finished. Missing while the run is active.
created_at
When the run started.
definition_display_name
The workflow’s spec.name.
definition_generation
The version of the workflow that ran. The number increases each time the definition changes.
definition_name
The workflow’s metadata.name.
definition_namespace
The namespace the workflow belongs to, for example, stacks-<STACK_ID>.
definition_spec
Only in the response for one run. The definition as it was when the run started. Missing for some older runs.
definition_uid
The workflow’s metadata.uid. Empty for a trigger run whose definition had no metadata.uid.
error_message
Present on every failed run. Explains why the run failed, for example, when a secret or resource couldn’t load or a step failed. To find the step that failed, check each step’s status and error.
execution_id
With instance_id, identifies the run.
instance_id
With execution_id, identifies the run.
stack_id
The ID of the stack that ran the workflow.
status
active, completed, or failed.
steps
Only in the response for one run. The steps that ran. Refer to Step fields.
triggering_event
What started the run. An event-started run shows the event name with your stack’s instance ID, for example, grafana_irm_app.123.incident.updated. A schedule run shows schedule. A run from the run endpoint shows api. A run from the editor or the trigger endpoint shows manual.
Step fields
Each entry in a run’s steps list includes the following fields.
Field
Description
completed_at
When the step finished.
depth
The number of branches that contain the step. Missing for top-level steps.
error
Why the step failed, or null if it didn’t fail.
inputs
The step’s inputs after Workflows filled in expressions. Secret values show [REDACTED].
name
The step’s id from the definition.
outputs
The values the step produced.
parent_step_id
For a step inside a branch, the ID of the step that holds the branch.
scheduled_at
When the step started.
status
active, completed, or failed.
step_name
The step’s display name from the definition.
step_type
The step’s type, for example, transform.
Error codes
The API returns the following HTTP status codes for errors.
Status
Meaning
400 Bad Request
The definition, request body, or a query parameter isn’t valid. The message names each problem.
401 Unauthorized
The token is missing, invalid, or expired.
403 Forbidden
The service account doesn’t have the role or folder access the request needs.
404 Not Found
No workflow or run matches the name or IDs in the URL.
405 Method Not Allowed
The HTTP method isn’t allowed for that endpoint.
409 Conflict
A workflow with that name already exists, or someone changed the workflow after you read it.
413 Content Too Large
The run or trigger request body is larger than 5 MB.
422 Unprocessable Entity
You tried to run a workflow that’s turned off, or you sent a PUT request without metadata.resourceVersion. To run a workflow that’s turned off, use the trigger endpoint.
500 Internal Server Error
Workflows couldn’t complete the request.
503 Service Unavailable
Workflows is temporarily unavailable. Try the request again later.
