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.
Workflows API reference
Note
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 .../ui/activity/stats | Counts runs by status over a time range, in time buckets. Refer to Activity stats. |
GET .../ui/activity/finished-runs | Gets the latest finished run of each workflow. Refer to Last runs response. |
GET .../runs | Lists runs across all workflows, newest first. Accepts the list runs parameters. |
GET .../runs/<DEFINITION_UID> | Lists the runs of one workflow, newest first. Accepts the list runs parameters. |
GET .../runs/<DEFINITION_UID>/<INSTANCE_ID>/<EXECUTION_ID> | Gets one run, including the result of each step. |
GET .../runs/<DEFINITION_UID>/<INSTANCE_ID>/<EXECUTION_ID>/progress | Gets the step-by-step progress events of one run. Optional: since_id returns only events after that event ID. |
GET .../types/steps | Lists the step types available on your stack, with their inputs and outputs. |
GET .../types/triggers | Lists the event types that can start a workflow. |
POST .../workflows/<NAME>/run | Runs a saved, enabled workflow. Refer to Run request body. |
POST .../workflows/<NAME>/trigger | 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.
The error and folder_uid parameters, and the 30-day limit on the time range, apply only to GET .../runs.
| 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. When you send both created_after and created_before to GET .../runs, the range between them can be at most 30 days, plus one hour so that 30 local days that include a daylight saving change are accepted, and created_before can’t be earlier than created_after. |
error | Only for GET .../runs. Return only failed runs whose error_message contains this text. The search ignores case and accepts up to 256 characters. Wildcard characters such as % and _ match themselves. You can combine it with status=failed, but not with another status. |
folder_uid | Only for GET .../runs. Return only runs of workflows that are in this folder now. When you move a workflow to another folder, its earlier runs move with it. |
status | Return only runs with this status: active, completed, or failed. |
Activity stats
GET .../ui/activity/stats counts the runs in a time range by status, in time buckets that you can plot as a chart.
The totals are the sum of the buckets.
It accepts the following query parameters.
| Parameter | Description |
|---|---|
created_after | Required. Count only runs created at or after this time. Use the RFC 3339 format. |
created_before | Required. Count only runs created before this time. Use the RFC 3339 format. Unlike the list runs parameter of the same name, this time is not included. The range can be at most 30 days, plus one hour so that 30 local days that include a daylight saving change are accepted. |
definition_uid | Count only the runs of this workflow. |
folder_uid | Count only runs of workflows that are in this folder now. |
timezone | An IANA time zone name, for example, Europe/Berlin. It sets where daily and six-hour buckets begin. The default is UTC. |
The response looks like the following example.
{
"totals": { "total": 3, "completed": 1, "failed": 1, "active": 1 },
"interval_seconds": 3600,
"buckets": {
"time": [1782864000000, 1782867600000],
"completed": [1, 0],
"failed": [0, 1],
"active": [0, 1]
}
}| Field | Description |
|---|---|
buckets.active | The number of active runs in each bucket. |
buckets.completed | The number of completed runs in each bucket. |
buckets.failed | The number of failed runs in each bucket. |
buckets.time | The start of each bucket, in Unix milliseconds. Every list in buckets has one entry per bucket, including buckets with no runs. |
interval_seconds | The size of each bucket. It is 3600 for ranges up to 48 hours, 21600 for ranges up to 7 days, and 86400 for longer ranges. |
totals | The number of runs in the whole range: total, completed, failed, and active. |
Daily buckets begin at midnight in the time zone you send. Six-hour buckets begin at 00:00, 06:00, 12:00, and 18:00 there. A day that changes between standard time and daylight saving time is still one bucket.
Last runs response
GET .../ui/activity/finished-runs takes no parameters.
It returns the latest finished run, which means a completed or failed run, of each workflow, keyed by the workflow’s metadata.uid.
A workflow with no finished run isn’t in the response.
{
"last_runs": {
"<DEFINITION_UID>": { "status": "failed", "created_at": "2026-09-01T12:30:00Z" }
}
}| Field | Description |
|---|---|
created_at | When the run started. |
status | 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. |
steps_processed | The number of steps the run executed. It doesn’t count steps that are turned off, which the run skips. Missing while the run is active, and on runs that finished before Workflows started recording it. |
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. |
504 Gateway Timeout | The request timed out. Try the request again. |
Related resources
Was this page helpful?
Related resources from Grafana Labs


