Workflows API

Workflows execute SQL on demand or on a schedule and send read-query results to HTTP or table sinks. See the workflow guide for SQL behavior and delivery guarantees.

All workflow endpoints require organization and cluster query parameters, using their names, and an admin API key, a user session bearer token, or an OAuth token with full_access. Admin API keys can read and manage workflows only in their bound organization and cluster; other API key permissions, including custom database roles, are not supported. Organization members can read workflows, runs, logs, and metrics; organization administrators can create, run, update, and delete workflows, and cancel runs.

Workflows belong to the organization and execute with organization credentials. Expiring or revoking the API key used to create a workflow prevents further API access with that key but does not stop the workflow. Pause or delete the workflow to stop future scheduled executions.

A disabled workflow service returns 503.

GET `/v1/workflows`

List workflows in the selected organization and cluster.

{ "workflows": [] }

POST `/v1/workflows`

Create a workflow. Returns 201 with the saved workflow, including its id, revision, created_at, updated_at, and sink metadata.

{
  "name": "high-volume-customers",
  "database": "default",
  "sql": "SELECT customer_id, count() AS total FROM events GROUP BY customer_id HAVING total > 100",
  "interval_seconds": 5,
  "enabled": true,
  "sinks": []
}

enabled defaults to true, interval_seconds to 1, and sinks to an empty list. Intervals must be whole seconds from 1 to 86,400 seconds. Each cluster supports up to 100 workflows, including paused workflows. Names are trimmed and lowercased and must be unique in the cluster.

GET `/v1/workflows/{workflow_id}`

Get a workflow and its schedule state. HTTP sink URLs and header values are write-only; responses include configuration metadata without those secrets.

PATCH `/v1/workflows/{workflow_id}`

Update the supplied fields and return the saved workflow. Set enabled to false to pause or true to resume. Omitted fields retain their existing values.

{ "enabled": false, "interval_seconds": 10 }

Supplying sinks replaces the full list. Preserve existing sink IDs when editing; omit id for new sinks. An empty list removes every sink. See sink configuration for HTTP credentials and table sinks.

DELETE `/v1/workflows/{workflow_id}`

Delete the workflow and its schedule. Returns 204 with no response body.

POST `/v1/workflows/{workflow_id}/runs`

Start an execution using the saved definition without changing its schedule. Requires an organization administrator or admin API key. No request body is required. Returns 202 with id, workflow_id, and source: "manual". The optional Idempotency-Key header accepts 1–128 visible ASCII characters without spaces. Reusing a key recovers the same execution while Temporal retains it. See explicit runs for revision checks, overlap, and delivery semantics.

POST `/v1/workflows/{workflow_id}/runs/{run_id}/cancel`

Request cancellation of one manual or scheduled execution. Requires an organization administrator or admin API key, with the same organization and cluster query parameters as the other workflow endpoints. No body is required. Returns 202 with an empty body once cancellation is accepted.

curl -X POST \
  "$RAWTREE_URL/v1/workflows/$WORKFLOW_ID/runs/$RUN_ID/cancel?organization=$ORGANIZATION&cluster=$CLUSTER" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

Cancellation is asynchronous and requires a worker to process it. Use the runs list to inspect the eventual status. It preserves execution history, other concurrent runs, and future scheduled executions. It does not roll back completed writes or recall deliveries already handed off to sinks. Query cleanup can take time, especially when a database replica is unavailable.

Repeating cancellation is safe: a pending request or an already canceled run returns 202. A run that has otherwise finished returns 409. Unknown runs, runs belonging to another workflow, and deleted workflows return 404. Because run lookup uses Temporal visibility, a newly started run may briefly return 404; retry once it appears in the runs list. A 503 means acceptance could not be confirmed; retry cancellation for the same run.

GET `/v1/workflows/{workflow_id}/runs`

List manual and scheduled executions retained by Temporal for this workflow. limit defaults to 20 and accepts 1–100. This is a per-page limit, not a total history limit. Pass next_cursor as cursor to request another page for the same workflow. The page size may change between requests. next_cursor: null means there are no more pages; an empty page with a cursor can still be continued.

{
  "runs": [
    {
      "id": "01a10ffc-b4f7-7871-859c-6353f93d875f",
      "workflow_id": "d668a6c1-1904-4a27-b113-ef54b5435483",
      "source": "manual",
      "status": "running",
      "started_at": "2026-10-06T10:32:00Z",
      "finished_at": null
    }
  ],
  "next_cursor": null
}

id is the Temporal run ID and matches the ID returned by POST. source is manual or scheduled. status is running, completed, failed, canceled, terminated, continued_as_new, timed_out, or paused. Timestamps use RFC 3339 in UTC; finished_at is null until the execution closes.

Active runs appear first by descending start time, then finished runs by descending finish time. Temporal visibility is eventually consistent: recent starts and status changes may appear after a delay. Pagination reflects live history, so refresh from the first page to see current state. Runs remain available after pausing or removing a schedule, until Temporal expires their history. Deleting the saved workflow makes its runs endpoint return 404.

Execution status is separate from SQL and sink delivery outcomes. Inspect the workflow logs for those details. Invalid limits or cursors return 400; an unavailable execution service returns 503.

GET `/v1/workflows/{workflow_id}/logs`

List execution and delivery history. Optional from (inclusive) and to (exclusive) are Unix milliseconds and default to the last 24 hours. Ranges can cover up to seven days. limit defaults to 100 and accepts 1–200.

The response contains logs, from, to, and next_cursor. Each log includes event_type (for example, workflow.evaluated) and workflow_revision. Delivery records identify the sink with sink_id and sink_type. Pass the returned from, to, and next_cursor as cursor to fetch older logs within the same window. History is best-effort observability data.

GET `/v1/workflows/{workflow_id}/metrics`

Get bucketed execution, match, successful sink delivery, and error counts. Optional from and to use the same bounds and defaults as logs. The response contains points, totals, from, and to; each point includes bucket_ms, executions, matches, sink_events, and errors.

Workflows API

On this page