Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

List runs

list_runs

Read-only

List an agent's run history, newest first, showing status, timing, and attributed cost; paginate with a cursor when more runs exist.

Instructions

List an agent's run history, most recently STARTED first, with each run's status, timing and attributed cost. Returns the newest 20 runs unless you pass limit (maximum 100). When more history exists the result carries next_cursor; pass it back as cursor for the next page, and stop when it is absent. Each row's session_id (the same value as thread_id) continues that conversation through invoke_agent. tool_progress is null for a terminal run and for a run with no telemetry; a non-terminal row reports the same progress get_run_result does. A row with input_expired is parked on a question its session has already moved past — start a new run rather than answering it.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	How many runs to return, newest first (default 20, maximum 100).
`cursor`	No	The next_cursor from a previous list_runs result, to continue where it stopped. Omit for the newest page.
`agent_id`	Yes	The agent's UUID.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`items`	Yes	One page of the agent's runs, most recently started first.
`next_cursor`	No	Pass this back as cursor to read the next page. Absent when this page is the end of the history.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.16.2Sep 21, 2026

addedOutput schema / properties / items / items / properties / advisor

Added value: +{
+  "additionalProperties": false,
+  "description": "Gross advisor consumption for the turn; the cap compares against this amount.",
+  "properties": {
+    "calls_allowed": {
+      "type": "integer"
+    },
+    "calls_used": {
+      "type": "integer"
+    },
+    "spend_cap_micro_usd": {
+      "type": [
+        "null",
+        "integer"
+      ]
+    },
+    "spend_micro_usd": {
+      "description": "Gross advisor consumption for the turn; the cap compares against this amount.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "calls_used",
+    "calls_allowed",
+    "spend_micro_usd"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / items / items / properties / credits / description
```
Added value: +"The net charge after any refund."
```

addedOutput schema / properties / items / items / properties / error / properties / upgrade

Added value: +{
+  "additionalProperties": false,
+  "description": "Which plan lifts the limit this run ended at, when it ended at one.",
+  "properties": {
+    "anonymous": {
+      "type": "boolean"
+    },
+    "limit": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "offer": {
+      "additionalProperties": false,
+      "properties": {
+        "discount_code": {
+          "type": "string"
+        },
+        "first_period_price_micro_usd": {
+          "type": "integer"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "discount_code",
+        "first_period_price_micro_usd",
+        "message"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "plan": {
+      "type": "string"
+    },
+    "remedies": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string"
+          },
+          "limits": {
+            "additionalProperties": false,
+            "properties": {
+              "disk_gb": {
+                "type": "integer"
+              },
+              "max_active_workflows": {
+                "type": "integer"
+              },
+              "max_agents": {
+                "type": "integer"
+              },
+              "max_concurrent_runs": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "max_concurrent_runs",
+              "max_agents",
+              "max_active_workflows",
+              "disk_gb"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "offer": {
+            "additionalProperties": false,
+            "properties": {
+              "discount_code": {
+                "type": "string"
+              },
+              "first_period_price_micro_usd": {
+                "type": "integer"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "discount_code",
+              "first_period_price_micro_usd",
+              "message"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "plan": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "usd_cents_per_month": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "kind",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "limit",
+    "plan",
+    "message",
+    "remedies"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / items / items / properties / gross_micro_usd

Added value: +{
+  "description": "Gross consumption before any refund.",
+  "type": "integer"
+}

addedOutput schema / properties / items / items / properties / refund_reason
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / items / items / properties / refund_withheld_reason
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / items / items / properties / refunded_micro_usd

Added value: +{
+  "description": "The refund reported once for this run.",
+  "type": "integer"
+}

addedOutput schema / properties / items / items / properties / usage_by_role

Added value: +{
+  "additionalProperties": false,
+  "description": "Gross consumption by role; credits sum to gross_micro_usd and refunds appear only in refunded_micro_usd.",
+  "properties": {
+    "advisor": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "type": "integer"
+        },
+        "credits": {
+          "type": "integer"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "credits",
+        "tokens",
+        "calls"
+      ],
+      "type": "object"
+    },
+    "executor": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "type": "integer"
+        },
+        "credits": {
+          "type": "integer"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "credits",
+        "tokens",
+        "calls"
+      ],
+      "type": "object"
+    },
+    "reviewer": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "type": "integer"
+        },
+        "credits": {
+          "type": "integer"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "credits",
+        "tokens",
+        "calls"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "executor",
+    "advisor",
+    "reviewer"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedOutput schema / properties / items / items / required

Previous value: -[
-  "id",
-  "agent_id",
-  "thread_id",
-  "session_id",
-  "status",
-  "origin",
-  "started_at",
-  "credits",
-  "tokens",
-  "tool_progress"
-]New value: +[
+  "id",
+  "agent_id",
+  "thread_id",
+  "session_id",
+  "status",
+  "origin",
+  "started_at",
+  "credits",
+  "tokens",
+  "advisor",
+  "tool_progress"
+]

Changed3 schema fields changedv0.16.0Sep 19, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "The next_cursor from a previous list_runs result, to continue where it stopped. Omit for the newest page.",
+  "type": "string"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "How many runs to return, newest first (default 20, maximum 100).",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "items": {
+      "description": "One page of the agent's runs, most recently started first.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "agent_id": {
+            "description": "The agent that ran it.",
+            "type": "string"
+          },
+          "cause": {
+            "type": "string"
+          },
+          "command_error": {
+            "type": "string"
+          },
+          "command_state": {
+            "type": "string"
+          },
+          "continuation_run_id": {
+            "type": "string"
+          },
+          "credits": {
+            "type": [
+              "null",
+              "integer"
+            ]
+          },
+          "ended_at": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "error": {
+            "additionalProperties": false,
+            "description": "Why a terminal error or cancelled run failed, and what to do about it. Absent for a run that is still going or that finished normally.",
+            "properties": {
+              "class": {
+                "description": "The failure class: the run's terminal cause, or \"unknown\" when none was recorded.",
+                "type": "string"
+              },
+              "message": {
+                "description": "What happened, and whether the work was charged.",
+                "type": "string"
+              },
+              "next_step": {
+                "description": "What to do about it.",
+                "type": "string"
+              },
+              "retryable": {
+                "description": "Whether sending the same message again could plausibly succeed.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "class",
+              "message",
+              "retryable",
+              "next_step"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "id": {
+            "description": "The run's public identifier; pass it to get_run_result as run_id.",
+            "type": "string"
+          },
+          "input_expired": {
+            "description": "True when this run is parked on a question its session has moved past: a later run in the same conversation has completed, so answering it would resume a superseded turn. Do not answer it; start a new run instead.",
+            "type": "boolean"
+          },
+          "input_status": {
+            "type": "string"
+          },
+          "input_updated_at": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "last_heartbeat_at": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "origin": {
+            "description": "What started this run: user, schedule, email, background, agent or agent_result.",
+            "type": "string"
+          },
+          "parent_run_id": {
+            "type": "string"
+          },
+          "resume_run_id": {
+            "type": "string"
+          },
+          "resume_status": {
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          },
+          "session_id": {
+            "description": "The conversation this run belongs to; pass it to invoke_agent as session_id to continue it. Identical to thread_id.",
+            "type": "string"
+          },
+          "started_at": {
+            "type": "string"
+          },
+          "status": {
+            "description": "The run's status: queued, running, awaiting_input, completed, error or cancelled.",
+            "type": "string"
+          },
+          "stop_reason": {
+            "type": "string"
+          },
+          "thread_id": {
+            "description": "The conversation this run belongs to. Identical to session_id.",
+            "type": "string"
+          },
+          "tokens": {
+            "type": [
+              "null",
+              "integer"
+            ]
+          },
+          "tool_progress": {
+            "additionalProperties": false,
+            "description": "Durable tool execution progress, from the same telemetry get_run_result reads. Null for a run with no telemetry, and for a terminal run, which has no call in flight to report.",
+            "properties": {
+              "active_tools": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "started_at": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "name",
+                    "started_at"
+                  ],
+                  "type": "object"
+                },
+                "type": [
+                  "null",
+                  "array"
+                ]
+              },
+              "completed_count": {
+                "type": "integer"
+              },
+              "last_completed_at": {
+                "type": [
+                  "null",
+                  "string"
+                ]
+              }
+            },
+            "required": [
+              "active_tools",
+              "completed_count"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "upstream_status": {
+            "description": "The model provider's HTTP status when this run died on an upstream fault; absent otherwise.",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "id",
+          "agent_id",
+          "thread_id",
+          "session_id",
+          "status",
+          "origin",
+          "started_at",
+          "credits",
+          "tokens",
+          "tool_progress"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "next_cursor": {
+      "description": "Pass this back as cursor to read the next page. Absent when this page is the end of the history.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "items"
+  ],
+  "type": "object"
+}

Addedv0.7.0Aug 9, 2026
Removedv0.3.0Jul 26, 2026
First observedv0.1.0Jul 4, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint/idempotentHint/openWorldHint; the description adds substantial behavior beyond that: default/max page size, next_cursor contract, the session_id==thread_id equivalence, and the semantics of tool_progress (null for terminal or no-telemetry runs, otherwise matching get_run_result). The input_expired explanation is exactly the kind of non-obvious state semantics that would otherwise be discoverable only by trial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then paging, then per-row semantics, then the input_expired edge case — a logical order. It is a dense paragraph rather than a list, but each clause carries new information and nothing appears to be filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, ordering, paging, key output fields, cross-tool linkage (invoke_agent, get_run_result), and the one genuinely confusing row state (input_expired). Given an output schema and full annotation coverage, this is complete enough for correct invocation without opening other tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is documented, so baseline is 3. The description restates the limit default/max and the cursor round-trip in prose, which reinforces but does not meaningfully extend the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List an agent's run history') and immediately specifies sort order and the fields returned (status, timing, attributed cost). An agent can distinguish this from list_agents, list_pending_inputs, or get_run_result from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the sibling tools and their relationship: session_id 'continues that conversation through invoke_agent', and input_expired rows should lead the agent to 'start a new run rather than answering it' — routing away from answer_pending_input. It also defines the pagination stop condition (when next_cursor is absent).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.