LoopLlama
Get API access
API reference

Runs

A run is a single execution of a workflow against one input. Runs execute the crew sequentially and record a step per agent.

The run object#

idstringoptional
Unique identifier for the run.
workflow_idstringoptional
The workflow this run belongs to.
statusstringoptional
One of queued, running, waiting_input, completed, or failed. A run sits in waiting_input when an agent has paused for a human — see Respond to a paused run.
inputstringoptional
The input the run was triggered with.
outputstring | nulloptional
The final agent's output. null until the run completes.
errorstring | nulloptional
Failure message, including which step failed. null unless the run failed.
total_stepsintegeroptional
Number of steps executed so far.
tokens_inintegeroptional
Total input tokens consumed across all steps.
tokens_outintegeroptional
Total output tokens produced across all steps.
started_atstring | nulloptional
ISO 8601 timestamp when execution began, or null while queued.
finished_atstring | nulloptional
ISO 8601 timestamp when the run reached a terminal state, or null.
created_atstringoptional
ISO 8601 timestamp when the run was created.
pendingobject | nulloptional
The request awaiting a human. null unless status is waiting_input. Has kind ("input" or "approval"), prompt (the question, or a short summary of the action), and for approvals tool + tool_input (the tool and arguments awaiting your go-ahead).
stepsStep[]optional
Per-agent steps, ordered by execution. Returned only by Retrieve a run.

The step object

idstringoptional
Unique identifier for the step.
orderintegeroptional
Zero-based position in the crew.
rolestringoptional
The agent role that produced this step.
modelstringoptional
The model used for this step.
inputstringoptional
The prompt this agent received (original input plus prior output).
outputstring | nulloptional
The agent's output, or null if it hasn't finished or errored.
errorstring | nulloptional
Error message if this step failed.
tokens_inintegeroptional
Input tokens consumed by this step.
tokens_outintegeroptional
Output tokens produced by this step.
started_atstring | nulloptional
ISO 8601 timestamp the step started.
finished_atstring | nulloptional
ISO 8601 timestamp the step finished.

Trigger a run#

POST/v1/workflows/{id}/runs

Queues a run for the given workflow and starts executing it asynchronously. Responds with 202 Accepted and the run in the queued state. Returns 409 Conflict if the workflow is paused, or 404 if it isn't found.

Path parameters

idstringrequired
The workflow id to run.

Body parameters

inputstringrequired
The task for the crew, 1–16,000 characters.

Request

bash
curl -X POST https://api.loopllama.ai/v1/workflows/ckva.../runs \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Draft a 200-word brief on a new feature-flag system."}'

Response

json
{
  "data": {
    "id": "ckrun1...",
    "workflow_id": "ckva...",
    "status": "queued",
    "input": "Draft a 200-word brief on a new feature-flag system.",
    "output": null,
    "error": null,
    "total_steps": 0,
    "tokens_in": 0,
    "tokens_out": 0,
    "started_at": null,
    "finished_at": null,
    "created_at": "2026-05-20T17:10:00.000Z"
  }
}

List runs for a workflow#

GET/v1/workflows/{id}/runs

Returns the workflow's 50 most recent runs, newest first. Step details are omitted from list responses — retrieve a run by id to get them.

Request

bash
curl https://api.loopllama.ai/v1/workflows/ckva.../runs \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Response

json
{
  "data": [
    {
      "id": "ckrun1...",
      "workflow_id": "ckva...",
      "status": "completed",
      "input": "Draft a 200-word brief...",
      "output": "Feature flags let teams...",
      "error": null,
      "total_steps": 2,
      "tokens_in": 412,
      "tokens_out": 286,
      "started_at": "2026-05-20T17:10:01.000Z",
      "finished_at": "2026-05-20T17:10:09.000Z",
      "created_at": "2026-05-20T17:10:00.000Z"
    }
  ]
}

Retrieve a run#

GET/v1/runs/{id}

Fetches a single run including its ordered steps. Poll this endpoint until status is completed or failed.

Path parameters

idstringrequired
The run id.

Request

bash
curl https://api.loopllama.ai/v1/runs/ckrun1... \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Response

json
{
  "data": {
    "id": "ckrun1...",
    "workflow_id": "ckva...",
    "status": "completed",
    "input": "Draft a 200-word brief on a new feature-flag system.",
    "output": "Feature flags let teams ship safely...",
    "error": null,
    "total_steps": 2,
    "tokens_in": 412,
    "tokens_out": 286,
    "started_at": "2026-05-20T17:10:01.000Z",
    "finished_at": "2026-05-20T17:10:09.000Z",
    "created_at": "2026-05-20T17:10:00.000Z",
    "steps": [
      {
        "id": "ckstep1...",
        "order": 0,
        "role": "planner",
        "model": "claude-sonnet-4-6",
        "input": "Draft a 200-word brief...",
        "output": "1. Define feature flags...",
        "error": null,
        "tokens_in": 180,
        "tokens_out": 120,
        "started_at": "2026-05-20T17:10:01.000Z",
        "finished_at": "2026-05-20T17:10:04.000Z"
      },
      {
        "id": "ckstep2...",
        "order": 1,
        "role": "writer",
        "model": "claude-sonnet-4-6",
        "input": "Original request:\n...\n\nPrior agent output:\n--- planner ---\n...",
        "output": "Feature flags let teams ship safely...",
        "error": null,
        "tokens_in": 232,
        "tokens_out": 166,
        "started_at": "2026-05-20T17:10:04.000Z",
        "finished_at": "2026-05-20T17:10:09.000Z"
      }
    ]
  }
}
Polling cadence
Most runs finish within a few seconds per step. Poll every 1–2 seconds, and stop once status is completed or failed — and watch for waiting_input, which means the run has paused for you. The SDKs expose a poll() helper that does this for you — see SDKs.

Respond to a paused run#

POST/v1/runs/{id}/respond

When a workflow enables human-in-the-loop, a run can pause itself. An agent pauses to ask a question (when the workflow allows agents to request input) or to wait for approval before a sensitive action runs (sending email, writing to a CRM). While paused, status is waiting_input and the run's pending object describes what it needs. This endpoint supplies the answer or decision and resumes the run; it responds with 202 Accepted.

Path parameters

idstringrequired
The run id (must be in waiting_input).

Body parameters

actionstringrequired
"input" to answer a question; "approve" or "reject" to decide an approval. Must match the run's pending.kind.
inputstringoptional
The answer to the agent's question. Required when action is "input".
reasonstringoptional
Optional note passed back to the agent when action is "reject" (e.g. why you declined, or what to do instead).

Answer a question

bash
curl -X POST https://api.loopllama.ai/v1/runs/ckrun1.../respond \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "input", "input": "Use a friendly, concise tone and target SMB owners."}'

Approve or reject a sensitive action

bash
# Approve — the gated tool runs, then the agent continues
curl -X POST https://api.loopllama.ai/v1/runs/ckrun1.../respond \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}'

# Reject — the tool is skipped and the agent is told why
curl -X POST https://api.loopllama.ai/v1/runs/ckrun1.../respond \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "reject", "reason": "Do not email external addresses."}'

Response

json
{
  "data": {
    "id": "ckrun1...",
    "status": "running"
  }
}
The pause/resume loop
Poll Retrieve a run. When you see status: "waiting_input", read pending to learn what the agent needs, call this endpoint with the matching action, then keep polling. A run may pause more than once. Sending the wrong action for the current pending.kind returns 400; responding to a run that isn't paused returns 409.