Tool Reference

list_workflow_runs

List recent workflow runs with optional filtering.

List recent workflow runs with optional filtering by status or workflow type. Returns runs ordered by most recent first.

Parameters

Parameter Type Required Description
status string No Filter runs by status. One of: "pending", "running", "completed", "partial_complete", "failed", "cancelled"
workflowId string No Filter runs by workflow type (e.g., "ai_shop_checkup")
limit number No Maximum number of runs to return (default: 20, max: 100)
offset number No Number of runs to skip for pagination (default: 0)
companyId string Auto-injected Injected from your API key. Do not pass this.

Example Request

curl -X POST https://socialcrm.com/api/mcp-app \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "list_workflow_runs",
      "arguments": {
        "status": "completed",
        "limit": 5
      }
    }
  }'

Example Response

Parsed from result.content[0].text:

{
  "runs": [
    {
      "runId": "run_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "workflowId": "ai_shop_checkup",
      "status": "completed",
      "agentCount": 5,
      "creditsReserved": 25,
      "creditsConsumed": 25,
      "errorMessage": null,
      "startedAt": "2026-02-18T10:00:05.000Z",
      "completedAt": "2026-02-18T10:04:30.000Z",
      "createdAt": "2026-02-18T10:00:00.000Z"
    }
  ],
  "total": 12,
  "limit": 5,
  "offset": 0
}

Output Schema

Field Type Description
runs array List of workflow run summaries
runs[].runId string Run UUID
runs[].workflowId string Workflow type
runs[].status string Run status
runs[].agentCount number Number of agents
runs[].creditsReserved number Credits reserved
runs[].creditsConsumed number Credits consumed
runs[].errorMessage string | null Error message if failed
runs[].startedAt string | null ISO 8601 start timestamp
runs[].completedAt string | null ISO 8601 completion timestamp
runs[].createdAt string ISO 8601 creation timestamp
total number Total matching runs (for pagination)
limit number Page size used
offset number Offset used

Notes

  • Use offset and limit for pagination. The total field tells you how many matching runs exist.
  • The maximum limit is 100, even if a larger value is requested.
  • To get detailed per-agent status for a specific run, use get_run_status.