Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

List runs

list_runs

Read-only

Retrieve an agent's recent run history, newest first, showing status, timing, and cost. Use the cursor to page through older runs, up to 100 per request.

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.8/5.0

Behavior5/5

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

Annotations only declare readOnly=true, but the description richly discloses additional behavior: newest-first ordering, default/maximum limit, cursor pagination, null tool_progress semantics, the session_id/thread_id equivalence, and input_expired handling. This goes well beyond what annotations convey.

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

Conciseness5/5

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

The description is efficient and front-loaded with the core purpose. Each subsequent sentence covers a distinct operational concern such as pagination, session continuation, progress reporting, or terminal-state edge cases—no filler or redundancy.

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?

With an output schema present and annotations covering read-only behavior, the description still supplies all practical details needed to use the tool correctly: ordering, limits, cursor flow, session continuation, null fields, and a caution about input_expired rows. Nothing essential is missing.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds meaningful context beyond the schema: the default page size, the instruction to pass next_cursor back as cursor, when to stop paginating, and the semantic meaning of row fields like session_id and input_expired. These details materially help an agent call the tool correctly.

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?

The description clearly identifies the resource ('an agent's run history'), the action ('List'), and the ordering ('most recently STARTED first'). It also distinguishes this from sibling list tools by specifying run-level details like status, timing, cost, and pagination.

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

Usage Guidelines4/5

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

The description gives clear procedural guidance for pagination ('pass it back as cursor... stop when it is absent') and explains when to continue a session via invoke_agent. It references get_run_result for progress semantics but does not explicitly state when to prefer list_runs over that sibling, so it falls just short of full exclusion guidance.

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