Skip to content
DocumentationAPI ReferenceChangelog
API ReferenceTalon Studio v1.0.2-beta

Agents

Inspect AI agent runs and their step timelines.

List agent runs

GET/api/v1/agent-runsagents:read

List agent runs in the token's reach, newest first.

Query parameters
workspaceIdstring (UUID) · optional
Filter to one workspace. Org-level runs (no workspace) are always included.
limitinteger · optional
1–200, default 50.
Response
idstring (UUID)
workspaceIdstring (UUID) · nullable
Null for an org-level run.
agentNamestring
triggerstring
manual | schedule | change_request_merged | webhook | kanban | coverage_gap | kev | kev_coverage_gap | validation_failure | pipeline_failure | soc_triage | handoff | rule_health | threat_intel | change_request_review
statusstring
running | succeeded | failed
summarystring · nullable
proposalsinteger
stagedinteger
failuresinteger
changeRequestIdsstring[]
Draft change requests the run staged. Agents never merge.
startedAtstring (ISO 8601)
finishedAtstring (ISO 8601) · nullable
Returned as { data: [...] }, ordered by startedAt descending.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/agent-runs?workspaceId=…&limit=20"
Response
{
  "data": [
    {
      "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f80",
      "workspaceId": "d41f0000-0000-4000-8000-000000000000",
      "agentName": "Detection Engineer",
      "trigger": "coverage_gap",
      "status": "succeeded",
      "proposals": 3,
      "staged": 1,
      "failures": 0
    },
    {
      "id": "2b8a4d61-9f3c-4e70-a1b8-6c5d4e3f2a19",
      "workspaceId": "d41f0000-0000-4000-8000-000000000000",
      "agentName": "Triage Analyst",
      "trigger": "soc_triage",
      "status": "running",
      "proposals": 0,
      "staged": 0,
      "failures": 0
    }
  ]
}

Get agent run

GET/api/v1/agent-runs/{id}agents:read

Fetch one agent run with its step timeline.

Path parameters
idstring (UUID)required
Query parameters
workspaceIdstring (UUID) · optional
Restricts the lookup to that workspace (and org-level runs). A run outside the token's reach returns 404.
Response
idstring (UUID)
workspaceIdstring (UUID) · nullable
agentNamestring
triggerstring
manual | schedule | change_request_merged | webhook | kanban | coverage_gap | kev | kev_coverage_gap | validation_failure | pipeline_failure | soc_triage | handoff | rule_health | threat_intel | change_request_review
statusstring
running | succeeded | failed
summarystring · nullable
taskstring · nullable
proposalsinteger
stagedinteger
failuresinteger
changeRequestIdsstring[]
inputTokensinteger
outputTokensinteger
startedAtstring (ISO 8601)
finishedAtstring (ISO 8601) · nullable
stepsarray
In order: seq (integer), kind (tool | message), status (ok | error), label, toolName (the raw tool name for kind=tool; always null for kind=message), detail (a short summary: the tool's arguments and result for a tool step, the message text for a message step), createdAt.
Returned as { data: { … } }.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/agent-runs/{id}"
Response
{
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f80",
    "agentName": "Detection Engineer",
    "status": "succeeded",
    "steps": [
      {
        "seq": 1,
        "kind": "tool",
        "status": "ok",
        "label": "Queried SIEM evidence",
        "toolName": "lake_search",
        "detail": "42 matching events for sourcetype=wineventlog",
        "createdAt": "2026-06-30T14:02:11.000Z"
      },
      {
        "seq": 2,
        "kind": "message",
        "status": "ok",
        "label": "Proposed detection",
        "toolName": null,
        "detail": "Drafted a brute-force detection from the evidence above",
        "createdAt": "2026-06-30T14:02:19.000Z"
      }
    ]
  }
}