Tool Reference

get_run_status

Get the full status of a workflow run.

Get the full status of a workflow run including overall status, per-agent progress, findings, and error details. Use this to poll a running workflow until completion.

Parameters

Parameter Type Required Description
runId string Yes The run ID returned by run_workflow
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": "get_run_status",
      "arguments": {
        "runId": "run_f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    }
  }'

Example Response

Parsed from result.content[0].text:

{
  "runId": "run_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "workflowId": "ai_shop_checkup",
  "status": "running",
  "agentCount": 5,
  "creditsReserved": 25,
  "creditsConsumed": 0,
  "summary": null,
  "errorMessage": null,
  "startedAt": "2026-02-18T10:00:05.000Z",
  "completedAt": null,
  "createdAt": "2026-02-18T10:00:00.000Z",
  "agents": [
    {
      "id": "agent_001",
      "role": "ai-simulator",
      "label": "AI Simulator",
      "status": "completed",
      "progress": 100,
      "findings": "Tested 12 queries across 4 platforms. Found 3 inaccuracies.",
      "errorMessage": null,
      "startedAt": "2026-02-18T10:00:05.000Z",
      "completedAt": "2026-02-18T10:01:30.000Z"
    },
    {
      "id": "agent_002",
      "role": "brand-monitor",
      "label": "Brand Monitor",
      "status": "running",
      "progress": 65,
      "findings": null,
      "errorMessage": null,
      "startedAt": "2026-02-18T10:00:05.000Z",
      "completedAt": null
    }
  ]
}

Output Schema

Field Type Description
runId string Run UUID
workflowId string Workflow type that was run
status string "pending", "running", "completed", "partial_complete", "failed", or "cancelled"
agentCount number Total number of agents in the workflow
creditsReserved number Credits reserved at launch
creditsConsumed number Credits actually consumed
summary string | null Final summary (populated on completion)
errorMessage string | null Error description if the run failed
startedAt string | null ISO 8601 timestamp when the run started executing
completedAt string | null ISO 8601 timestamp when the run finished
createdAt string ISO 8601 timestamp when the run was created
agents array Per-agent status details
agents[].id string Agent instance UUID
agents[].role string Agent role identifier
agents[].label string Human-readable agent name
agents[].status string Agent status
agents[].progress number Progress percentage (0-100)
agents[].findings string | null Agent findings/output (populated on completion)
agents[].errorMessage string | null Agent error if it failed
agents[].startedAt string | null ISO 8601 timestamp
agents[].completedAt string | null ISO 8601 timestamp

Notes

  • Poll at 5-10 second intervals. The run is complete when status is "completed", "partial_complete", or "failed".
  • partial_complete means some agents succeeded but others failed. Check individual agents[].status for details.
  • Returns an error if the runId does not exist or does not belong to your company.