get_runs
Retrieve a list of all protocol runs on Opentrons robots to monitor execution history and manage automated laboratory workflows.
Instructions
List all runs on the robot
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"robot_ip": "<robot_ip>"
},
"name": "get_runs"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| robot_ip | Yes | Robot IP address |
Implementation Reference
- index.js:1817-1869 (handler)The main handler function for the 'get_runs' tool. Fetches the list of protocol runs from the Opentrons robot API at /runs, formats them nicely, and returns up to 10 recent runs with status, creation time, protocol ID, and duration.
async getRuns(args) { const { robot_ip } = args; try { const data = await this.makeApiRequest( 'GET', `http://${robot_ip}:31950/runs` ); const runs = data.data || []; if (runs.length === 0) { return { content: [ { type: "text", text: `No runs found on robot.` } ] }; } const runList = runs.slice(0, 10).map(r => { const duration = r.completedAt && r.startedAt ? Math.round((new Date(r.completedAt) - new Date(r.startedAt)) / 1000 / 60) : null; return `**Run ${r.id}**\n` + ` Status: ${r.status}\n` + ` Created: ${new Date(r.createdAt).toLocaleString()}\n` + ` Protocol: ${r.protocolId || 'None'}\n` + ` Duration: ${duration ? `${duration} minutes` : 'N/A'}\n`; }).join('\n'); return { content: [ { type: "text", text: `Found ${runs.length} run${runs.length !== 1 ? 's' : ''} on robot${runs.length > 10 ? ' (showing latest 10)' : ''}:\n\n${runList}` } ] }; } catch (error) { return { content: [ { type: "text", text: `❌ Failed to get runs: ${error.message}` } ] }; } } - index.js:167-173 (schema)Input schema definition for the get_runs tool. Requires 'robot_ip' parameter.
inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" } }, required: ["robot_ip"] } - index.js:164-174 (registration)Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema for get_runs.
{ name: "get_runs", description: "List all runs on the robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" } }, required: ["robot_ip"] } }, - index.js:258-259 (registration)Registration and dispatch of get_runs handler in the CallToolRequestSchema switch statement.
case "get_runs": return this.getRuns(args);