API v1

Runs API

Run endpoints expose execution state, timing, trigger metadata, and redacted failure details. Secrets, raw credentials, and sensitive run text are redacted before public API responses.

Step 1

List recent runs by workspace, status, or workflow id.

Step 2

Fetch one run detail for troubleshooting and dashboard links.

Step 3

Use run ids returned by workflow run, webhook, and MCP calls.

Endpoints

GET/api/v1/runs?limit=10&status=success

List run summaries with cursor pagination and optional status/workflow filters.

Required scope: runs:read

curl https://www.finkmesh.com/api/v1/runs?limit=10&status=success \
  -H "Authorization: Bearer $FINKMESH_TOKEN"
{
  "data": [
    {
      "id": "run_123",
      "workflowId": "wf_123",
      "status": "success",
      "trigger": "api",
      "stepCount": 3
    }
  ],
  "pagination": { "limit": 10, "hasMore": false, "nextCursor": null },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
GET/api/v1/runs/{runId}

Fetch redacted run detail, workflow metadata, status, trigger, node results, and failure context.

Required scope: runs:read

curl https://www.finkmesh.com/api/v1/runs/{runId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN"
{
  "data": {
    "id": "run_123",
    "status": "success",
    "trigger": "api",
    "workflow": { "id": "wf_123", "name": "Lead routing" },
    "nodeResults": []
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Redaction

Run responses are designed for debugging without leaking credentials, bearer headers, OAuth tokens, or secret-shaped values.

Polling

After queueing a run, poll /api/v1/runs/{runId}. Back off on 429 and use FinkMesh-Request-Id for support.

Failed Run Example

Failed runs keep diagnostic metadata redacted. Use the run id and dashboard link for deeper operator review.

{
  "data": {
    "id": "run_123",
    "status": "error",
    "trigger": "api",
    "workflow": {
      "id": "wf_123",
      "name": "Lead routing"
    },
    "error": "A required connection needs attention.",
    "failedNodeName": "Send Slack message",
    "failedNodeError": "Connection needs reauthorization.",
    "links": {
      "dashboard": "https://www.finkmesh.com/dashboard/runs/run_123"
    }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Related Docs

Workflow APIErrors