---
title: "Execute a workflow"
method: POST
path: "/workflows/{action_id}/execute"
tags: ["Workflows"]
---

# Execute a workflow

`POST /workflows/{action_id}/execute`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/workflows/{action_id}/execute`
- Auth: HTTP bearer

Trigger a workflow run. Returns ``execution_id`` for polling.

A workflow with record steps or a record trigger runs them with its OWNER's
record access, and this run's input feeds them: the key must hold the object
scopes they exercise (403 ``missing_scopes``) and its member must own the
workflow or administer the org (403 ``owner_or_admin_required``, from the
workflow service, which receives the member as the verified identity). The
saved workflow is read before the run so that check is never skipped: when
it cannot be read, the answer is ``502`` and nothing runs.

Pins ``org_id`` server-side; the caller cannot override which org's
execution row is created. ``triggered_by`` defaults to the caller's
user id when not supplied.

If the workflow service takes the request but does not answer in time,
the answer is ``202`` with ``outcome`` ``started`` (run found, with its
``execution_id``) or ``unknown`` (check the executions list first), not a
502: the run may well be going. Send an ``Idempotency-Key`` to make retries
safe; a retry with the same key returns the first answer.

## Path parameters

- `action_id` string, required: Workflow action_id.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- object: ExecutionCreateRequest body.

## Response `200`

Successful Response

- object

## Other responses

- `202`: The run request reached the workflow service but no reply came back in time. ``outcome`` is ``started`` (the run was found; ``execution_id`` is set) or ``unknown`` (check ``GET /workflows/executions`` before retrying). Never a failure.
- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/89fc11143b70?raw)