--- title: "Workflows API reference | Grafana Cloud documentation" description: "Reference for the Grafana Workflows API, including endpoints, request bodies, list parameters, run and step fields, and error codes." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Workflows API reference > Note > > Grafana Workflows is currently in [public preview](/docs/release-life-cycle/). 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](/docs/grafana-cloud/platform/workflows/as-code/use-the-api). > Caution > > The run endpoints might change during public preview. ## Endpoints Every request needs an `Authorization: Bearer ` 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//definitions`, where *NAMESPACE* is `stacks-`. Expand table | Method and path | Description | |---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `DELETE .../definitions/` | Deletes a workflow. | | `GET .../definitions` | Lists workflows. | | `GET .../definitions/` | Gets one workflow. | | `PATCH .../definitions/` | 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/` | 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`. Expand table | Method and path | Description | |-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | `GET .../runs` | Lists runs across all workflows, newest first. Accepts the [list runs parameters](#list-runs-parameters). | | `GET .../runs/` | Lists the runs of one workflow, newest first. Accepts the [list runs parameters](#list-runs-parameters). | | `GET .../runs///` | Gets one run, including the result of each step. | | `GET .../runs////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//run` | Runs a saved, enabled workflow. Refer to [Run request body](#run-request-body). | | `POST .../workflows//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](#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. Expand table | 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 Expand table | 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. Expand table | 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. Expand table | 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-`. | | `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](#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. Expand table | 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. Expand table | 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 - [Use the API](/docs/grafana-cloud/platform/workflows/as-code/use-the-api) - [Use gcx](/docs/grafana-cloud/platform/workflows/as-code/use-gcx) - [Sample event payloads](/docs/grafana-cloud/platform/workflows/reference/event-payloads)