Skip to main content
API reference sections

Schema

ListRunsResponse

Type object

Shape

FieldTypeDescription
runsrequiredarray of RunHeader
sessionsobject

The provider session each listed run is being driven in on the device that answered, for the runs where there is one.

The same fact [RunExecution::session] carries about a single run, and deliberately not a header field for the same reason: a header is what a run means on every device, and which session is driving it here is execution state (D3, D15). The listing carries it so a surface that draws every run - the Agents navigator - can put a run's session underneath the run without one GET /v1/runs/{run} per row.

Absent for a run between attempts, for a run that has ended, and for every run another device is executing. #[serde(default)], so a listing from a worker that predates the field reads as no session known rather than failing to decode.

documentsobject

The Run document each listed run is registered as.

A run is a document in the workspace's manifest, and deleting one is that document going into the workspace's bin like every other document in Koru - which is a manifest edit, and the manifest belongs to the window rather than to this worker. So the listing says which document each run is, and the window that asks for a run to be deleted has the id it needs to move it.

#[serde(default)], so a listing from a worker that predates the field reads as no documents named rather than failing to decode.

trashedarray of TrashedRun

The runs of this workspace that are in the trash, newest deletion first. Absent from runs: a trashed run is not a run you are looking at any more, and the Agents navigator stops listing it the moment it goes.

Example
{
  "runs": [
    {
      "run": "00000000-0000-4000-8000-000000000000",
      "created_at_ms": 0,
      "requested_by": {
        "profile": "00000000-0000-4000-8000-000000000000",
        "kind": "person"
      },
      "objective": "string",
      "agent": {
        "kind": "built_in",
        "value": "string"
      },
      "requested_model": "string",
      "scope": {
        "kind": "none"
      },
      "context": [
        {
          "workspace": "00000000-0000-4000-8000-000000000000",
          "document": "00000000-0000-4000-8000-000000000000",
          "version": "00000000-0000-4000-8000-000000000000",
          "kind": "document"
        }
      ],
      "grants": [],
      "status": {
        "state": "created"
      },
      "failure_reason": "capability_not_negotiated",
      "environment": {
        "device": "string",
        "kind": "local_device"
      },
      "artifacts": [],
      "economics": {
        "orchestrator_turns": 0,
        "human_turns": 0,
        "turns_with_usage": 0,
        "input": {
          "known": 0,
          "unavailable_turns": 0
        },
        "output": {
          "known": 0,
          "unavailable_turns": 0
        },
        "cached_input": {
          "known": 0,
          "unavailable_turns": 0
        },
        "tool_calls": 0,
        "interventions": 0,
        "elapsed_ms": null,
        "models": [],
        "complete": false
      },
      "rating": {
        "rating": "good",
        "note": "string",
        "rated_by": {
          "profile": "00000000-0000-4000-8000-000000000000",
          "kind": "person"
        },
        "rated_at_ms": 0
      },
      "origin": {
        "origin": "manual"
      }
    }
  ],
  "sessions": {},
  "documents": {},
  "trashed": [
    {
      "header": {
        "run": "00000000-0000-4000-8000-000000000000",
        "created_at_ms": 0,
        "requested_by": {
          "profile": "00000000-0000-4000-8000-000000000000",
          "kind": "person"
        },
        "objective": "string",
        "agent": {
          "kind": "built_in",
          "value": "string"
        },
        "requested_model": "string",
        "scope": {
          "kind": "none"
        },
        "context": [
          {
            "workspace": "00000000-0000-4000-8000-000000000000",
            "document": "00000000-0000-4000-8000-000000000000",
            "version": "00000000-0000-4000-8000-000000000000",
            "kind": "document"
          }
        ],
        "grants": [],
        "status": {
          "state": "created"
        },
        "failure_reason": "capability_not_negotiated",
        "environment": {
          "device": "string",
          "kind": "local_device"
        },
        "artifacts": [],
        "economics": {
          "orchestrator_turns": 0,
          "human_turns": 0,
          "turns_with_usage": 0,
          "input": {
            "known": 0,
            "unavailable_turns": 0
          },
          "output": {
            "known": 0,
            "unavailable_turns": 0
          },
          "cached_input": {
            "known": 0,
            "unavailable_turns": 0
          },
          "tool_calls": 0,
          "interventions": 0,
          "elapsed_ms": null,
          "models": [],
          "complete": false
        },
        "rating": {
          "rating": "good",
          "note": "string",
          "rated_by": {
            "profile": "00000000-0000-4000-8000-000000000000",
            "kind": "person"
          },
          "rated_at_ms": 0
        },
        "origin": {
          "origin": "manual"
        }
      },
      "document": {},
      "trashed_at_ms": 0,
      "artifacts": "keep"
    }
  ]
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Used by

Generated from contract version 1. Last updated .

Privacy choices

Choose which optional tools Koru may use on this site. Your choice is saved in a cookie in this browser for 12 months. Privacy policy

Privacy choices

Keep you signed in, protect forms and remember your language and this choice.

Always on

PostHog and Google Analytics 4 measure page views and actions such as downloads, using cookies or local storage.

PostHog records how pages are used, with form inputs masked and private pages excluded. Needs Analytics.

Ahrefs Web Analytics measures visits and where they come from, and Google Ads measures whether our ads led to a visit or download.