{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/prep/sidebars.yaml","oas-products/prep/api/openapi.yaml":"oas-products/prep/api/openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["split","openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Start a protocol run","description":"Hamilton's Developer Portal is used to help reference and understand the APIs of Hamilton products.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"start-a-protocol-run"},"children":["Start a protocol run"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page provides step-by-step instructions for running a protocol using the Prep API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51666163467","level":2},"children":["Retrieve protocol list "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before running a protocol, review the protocols in the system to obtain the protocol ID of the desired protocol to run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocols/getprotocolsummaries","target":"_blank"},"children":["Retrieve the list of protocols"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetProtocolSummaries","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702081931","level":2},"children":["Create a protocol run "]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"51702114443"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating a protocol run prepares the system for protocol execution and loads the deck. Use a protocol ID found in the protocol list to send this request."]}]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating a protocol run requires the protocol ID, a simulation flag, and a recompile flag. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ProtocolId"]}," field is the numeric id assigned when the protocol was first created."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Simulation"]}," field to trigger a simulation of the protocol associated with the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ProtocolId"]}," field. All devices associated with the protocol are also simulated."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Recompile"]}," field forces the protocol to be recompiled even if it was already verified."]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["The instrument may need to initialize if this is not a simulation. Close the door during this step."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750798603"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/createrun","target":"_blank"},"children":["Create a new run, schedule, and populate load instructions"]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetRunStatus","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689565579","level":2},"children":["Load deck "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702174731","level":3},"children":["Get load instructions "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750837515"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the load instructions to verify the labware the protocol is expecting. "]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["PositionName"]}," field is the name assigned to the position for this run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["DeckPosition"]}," field is the ID of the deck position where the labware is placed. The positions are ordered from 1 to 8, where the rear left is 1, front left is 4, rear right is 5, and front right is 8."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwarePosition"]}," field is the labware site used for this run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwareClassification"]}," field describes the labware type (e.g., Plate, Tiprack)."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750833547"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getloadinstructions","target":"_blank"},"children":["Retrieve the load instructions"]},{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getloadinstructions","target":"_blank"},"children":[]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetRunStatus","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702180619","level":3},"children":["Complete protocol loading "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the labware has been placed on the deck, close the door and start the protocol run using ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"code"},"children":["Put"]}," load complete."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ProtocolId"]}," field is the numeric ID assigned when the protocol was first created."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Simulate"]}," field triggers a simulation of the protocol associated with the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ProtocolId"]}," field. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LoadCompleteAction"]}," field is the action to perform after the LoadComplete has been sent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ResidualTips"]}," field is where the tips are placed in the labware when the tip rack isn't full."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Barcodes"]}," field is a list of barcodes for each deck or labware position."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LiquidVolumes"]}," field is a list of liquids, volumes, and deck and labware positions used primarily for reagents and diluents."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/loadcomplete","target":"_blank"},"children":["Complete the loading for the run"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"LoadComplete","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702208139","level":2},"children":["Poll protocol status until completion "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"51702116875"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After all steps have been followed, wait for protocol execution to complete. Poll for the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["protocolRunState"]}," to be ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["0"]}," (idle), or until ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["isRunInProgress"]}," is ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["false"]},". "]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["A more advanced and efficient approach for this would be listening for events to determine when the correct state is reached."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ProtocolId"]}," field is the ID of the protocol currently running. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["RunDataId"]}," field is the ID of the run data of the current."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["IsRunInProgress"]}," field indicates whether the run is currently running or if it has completed or been aborted. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["IsSimulation"]}," field indicates whether the run is being simulated or if it is running on an instrument."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["StartTime"]}," field is the time the run started."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["EstimatedEndTime"]}," field is the time the run is expected to complete."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["EndPauseTime"]}," field is the total time of the pause step if it has a fixed duration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ProtocolName"]}," field is the name of the protocol being used in the current run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["CurrentStep"]}," field is the step ID that the run is currently processing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["PreLoadThermalDeviceUsed"]}," field indicates the thermal device (if any) installed for the run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["PreLoadHepaFiltration"]}," field indicates whether the instrument is using a HEPA filtration system."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750845835"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getrunstatus","target":"_blank"},"children":["Get the current run status"]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetRunStatus","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689673739","level":2},"children":["Execute protocol operations "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section describes the available operations for protocol execution: pausing, resuming, and aborting a protocol. Each operation requires the instrument to be in a specific state before executing. "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689674891","level":3},"children":["Available operations "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689667723","level":4},"children":["Pause a protocol "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To pause a protocol, the instrument must be in a ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Running"]}," state."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"Pause","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689686155","level":4},"children":["Resume a protocol "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To resume a protocol, the instrument must be in a ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Paused"]}," state. "]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["Never use the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Resume"]}," endpoint to start a protocol."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"Resume","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689691019","level":4},"children":["Abort a protocol "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52707346571"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This option is available when the instrument is in a ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Running"]}," or ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Paused"]}," state."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"AbortProtocolRun","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51689701259","level":2},"children":["Unload a protocol "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52707349131"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This option is available when the instrument is in an ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Aborted"]},", ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Initialized"]},", or ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["Terminated"]}," state."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"PostUnloadCleanup","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]}]},"headings":[{"value":"Start a protocol run","id":"start-a-protocol-run","depth":1},{"value":"Retrieve protocol list","id":"51666163467","depth":2},{"value":"Create a protocol run","id":"51702081931","depth":2},{"value":"Load deck","id":"51689565579","depth":2},{"value":"Get load instructions","id":"51702174731","depth":3},{"value":"Complete protocol loading","id":"51702180619","depth":3},{"value":"Poll protocol status until completion","id":"51702208139","depth":2},{"value":"Execute protocol operations","id":"51689673739","depth":2},{"value":"Available operations","id":"51689674891","depth":3},{"value":"Pause a protocol","id":"51689667723","depth":4},{"value":"Resume a protocol","id":"51689686155","depth":4},{"value":"Abort a protocol","id":"51689691019","depth":4},{"value":"Unload a protocol","id":"51689701259","depth":2}],"frontmatter":{"seo":{"title":"Start a protocol run"}},"lastModified":"2026-07-30T19:22:04.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pages/prep_recipe_protocol_start","userData":{"isAuthenticated":false,"teams":["anonymous"]}}