Public preview Grafana Cloud
Last reviewed: November 2, 2026

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 pathDescription
DELETE .../definitions/<NAME>Deletes a workflow.
GET .../definitionsLists workflows.
GET .../definitions/<NAME>Gets one workflow.
PATCH .../definitions/<NAME>Changes the fields in the request body and leaves the other fields unchanged.
POST .../definitionsCreates 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 pathDescription
GET .../ui/activity/statsCounts runs by status over a time range, in time buckets. Refer to Activity stats.
GET .../ui/activity/finished-runsGets the latest finished run of each workflow. Refer to Last runs response.
GET .../runsLists 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>/progressGets the step-by-step progress events of one run. Optional: since_id returns only events after that event ID.
GET .../types/stepsLists the step types available on your stack, with their inputs and outputs.
GET .../types/triggersLists the event types that can start a workflow.
POST .../workflows/<NAME>/runRuns a saved, enabled workflow. Refer to Run request body.
POST .../workflows/<NAME>/triggerRuns 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.

FieldTypeDescription
inputsObjectOptional: 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

FieldTypeDescription
definitionObjectThe complete workflow definition to run. Include metadata.uid to link the run to a saved workflow’s run history.
event_dataObjectOptional: 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.

ParameterDescription
afterA cursor for the next page. Use the next_cursor value from the previous response.
countThe number of runs to return. The default is 25, and the maximum is 100.
created_afterReturn only runs created at or after this time. Use the RFC 3339 date and time format, for example, 2026-09-01T00:00:00Z.
created_beforeReturn 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.
errorOnly 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_uidOnly 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.
statusReturn 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.

ParameterDescription
created_afterRequired. Count only runs created at or after this time. Use the RFC 3339 format.
created_beforeRequired. 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_uidCount only the runs of this workflow.
folder_uidCount only runs of workflows that are in this folder now.
timezoneAn 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.

JSON
{
  "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]
  }
}
FieldDescription
buckets.activeThe number of active runs in each bucket.
buckets.completedThe number of completed runs in each bucket.
buckets.failedThe number of failed runs in each bucket.
buckets.timeThe start of each bucket, in Unix milliseconds. Every list in buckets has one entry per bucket, including buckets with no runs.
interval_secondsThe 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.
totalsThe 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.

JSON
{
  "last_runs": {
    "<DEFINITION_UID>": { "status": "failed", "created_at": "2026-09-01T12:30:00Z" }
  }
}
FieldDescription
created_atWhen the run started.
statuscompleted or failed.

Run fields

Runs in list and run responses include the following fields.

FieldDescription
completed_atWhen the run finished. Missing while the run is active.
created_atWhen the run started.
definition_display_nameThe workflow’s spec.name.
definition_generationThe version of the workflow that ran. The number increases each time the definition changes.
definition_nameThe workflow’s metadata.name.
definition_namespaceThe namespace the workflow belongs to, for example, stacks-<STACK_ID>.
definition_specOnly in the response for one run. The definition as it was when the run started. Missing for some older runs.
definition_uidThe workflow’s metadata.uid. Empty for a trigger run whose definition had no metadata.uid.
error_messagePresent 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_idWith instance_id, identifies the run.
instance_idWith execution_id, identifies the run.
stack_idThe ID of the stack that ran the workflow.
statusactive, completed, or failed.
stepsOnly in the response for one run. The steps that ran. Refer to Step fields.
steps_processedThe 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_eventWhat 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.

FieldDescription
completed_atWhen the step finished.
depthThe number of branches that contain the step. Missing for top-level steps.
errorWhy the step failed, or null if it didn’t fail.
inputsThe step’s inputs after Workflows filled in expressions. Secret values show [REDACTED].
nameThe step’s id from the definition.
outputsThe values the step produced.
parent_step_idFor a step inside a branch, the ID of the step that holds the branch.
scheduled_atWhen the step started.
statusactive, completed, or failed.
step_nameThe step’s display name from the definition.
step_typeThe step’s type, for example, transform.

Error codes

The API returns the following HTTP status codes for errors.

StatusMeaning
400 Bad RequestThe definition, request body, or a query parameter isn’t valid. The message names each problem.
401 UnauthorizedThe token is missing, invalid, or expired.
403 ForbiddenThe service account doesn’t have the role or folder access the request needs.
404 Not FoundNo workflow or run matches the name or IDs in the URL.
405 Method Not AllowedThe HTTP method isn’t allowed for that endpoint.
409 ConflictA workflow with that name already exists, or someone changed the workflow after you read it.
413 Content Too LargeThe run or trigger request body is larger than 5 MB.
422 Unprocessable EntityYou 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 ErrorWorkflows couldn’t complete the request.
503 Service UnavailableWorkflows is temporarily unavailable. Try the request again later.
504 Gateway TimeoutThe request timed out. Try the request again.