Orchestrator - Robots requests

orchestrator

2023.10

false

Orchestrator API guide

Robots requests

Sample API requests for retrieving robot license keys and session status via the Robots and Sessions OData endpoints.

Retrieving robot statuses

Note:

If you want to extract the value of the LicenseKey parameter, you have to make a GET request to the /odata/Robots(Id) endpoint.

According to its ID

The following example enables you to view the current status of the Robot with the 749 Id.

GET

https://{yourDomain}/odata/Sessions?$top=10&$filter=Robot/Id eq 749&$select=State

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions(State)",
    "@odata.count": 1,
    "value": [
        {
            "State": "Available"
        }
    ]
}
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions(State)",
    "@odata.count": 1,
    "value": [
        {
            "State": "Available"
        }
    ]
}

According to its name

The following example enables you to view the current status of the Robot with the DocBot Name.

GET

https://{yourDomain}/odata/Sessions?$top=10&$filter=Robot/Name eq 'DocBot'&$select=State

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions(State)",
    "@odata.count": 1,
    "value": [
        {
            "State": "Available"
        }
    ]
}
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions(State)",
    "@odata.count": 1,
    "value": [
        {
            "State": "Available"
        }
    ]
}

Retrieving robot information according to its state: Example 1

The example below requests the first 10 Robots that have the Available status and sent a heartbeat in the last 2 minutes. Only the relevant robot information is displayed. You can check the heartbeat by using the Reporting Time parameter and subtract 2 minutes from the current time. As you might know, if a Robot has not sent a heartbeat in the last 2 minutes, it is flagged as unresponsive.

GET

https://{yourDomain}/odata/Sessions?$top=10&$filter=State eq 'Available' and ReportingTime gt 2018-03-05T03:48:04.147Z&$select=Robot&$expand=Robot

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions(Robot)",
    "@odata.count": 2,
    "value": [
        {
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "MBOBOC",
                "Name": "DocBot",
                "Username": "UIPATH\\MADALINA.BOBOC",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "doc_env,WR_env,Group1",
                "Id": 749,
                "ExecutionSettings": null
            }
        },
        {
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "midragomir",
                "Name": "mr-Rob",
                "Username": "uipath\\mircea.dragomir",
                "Description": "Alerts",
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "",
                "Id": 902,
                "ExecutionSettings": null
            }
        }
    ]
}
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions(Robot)",
    "@odata.count": 2,
    "value": [
        {
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "MBOBOC",
                "Name": "DocBot",
                "Username": "UIPATH\\MADALINA.BOBOC",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "doc_env,WR_env,Group1",
                "Id": 749,
                "ExecutionSettings": null
            }
        },
        {
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "midragomir",
                "Name": "mr-Rob",
                "Username": "uipath\\mircea.dragomir",
                "Description": "Alerts",
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "",
                "Id": 902,
                "ExecutionSettings": null
            }
        }
    ]
}

Retrieving robot information according to its state: Example 2

The following example looks for the top 10 Robots that have the Disconnected status and expands Robot information.

GET

https://{yourDomain}/odata/Sessions?$top=10&$filter=State eq 'Disconnected'&$expand=Robot

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions",
    "@odata.count": 2,
    "value": [
        {
            "State": "Disconnected",
            "ReportingTime": "2018-01-15T18:47:07.93Z",
            "Info": null,
            "IsUnresponsive": false,
            "Id": 718,
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "DESKTOP-PMFQGCB",
                "Name": "Stan",
                "Username": "Alex",
                "Description": null,
                "Type": "Unattended",
                "Password": null,
                "RobotEnvironments": "doc_env,a_invoke_env,Group1",
                "Id": 759,
                "ExecutionSettings": null
            }
        },
        {
            "State": "Disconnected",
            "ReportingTime": "2018-01-18T18:14:14.34Z",
            "Info": null,
            "IsUnresponsive": false,
            "Id": 730,
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "DESKTOP-PMFQGCB",
                "Name": "!~#$%^&*()_+=-",
                "Username": "dragomirmir",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "WR_env",
                "Id": 771,
                "ExecutionSettings": null
            }
        }
    ]
}
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Sessions",
    "@odata.count": 2,
    "value": [
        {
            "State": "Disconnected",
            "ReportingTime": "2018-01-15T18:47:07.93Z",
            "Info": null,
            "IsUnresponsive": false,
            "Id": 718,
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "DESKTOP-PMFQGCB",
                "Name": "Stan",
                "Username": "Alex",
                "Description": null,
                "Type": "Unattended",
                "Password": null,
                "RobotEnvironments": "doc_env,a_invoke_env,Group1",
                "Id": 759,
                "ExecutionSettings": null
            }
        },
        {
            "State": "Disconnected",
            "ReportingTime": "2018-01-18T18:14:14.34Z",
            "Info": null,
            "IsUnresponsive": false,
            "Id": 730,
            "Robot": {
                    "LicenseKey": null,
                "MachineName": "DESKTOP-PMFQGCB",
                "Name": "!~#$%^&*()_+=-",
                "Username": "dragomirmir",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "WR_env",
                "Id": 771,
                "ExecutionSettings": null
            }
        }
    ]
}

Retrieving robot information according to its ID

The following example retrieves the details of the Robot with the 216 Id. Please note that this Robot uses smart card authentication.

GET

https://{yourDomain}/odata/Robots(216)

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Robots/$entity",
    "LicenseKey": "fc157179-3724-4bb0-acd2-8261bef82d01",
    "MachineName": "CAPETRINA",
    "MachineId": 15,
    "Name": "Gustavee",
    "Username": "uipath\\john.smith",
    "ExternalName": null,
    "Description": null,
    "Type": "Development",
    "HostingType": "Standard",
    "ProvisionType": "Manual",
    "Password": null,
    "CredentialStoreId": null,
    "UserId": 45,
    "Enabled": true,
    "CredentialType": null,
    "RobotEnvironments": "",
    "IsExternalLicensed": false,
    "LimitConcurrentExecution": false,
    "Id": 216,
    "ExecutionSettings": {
        "ResolutionHeight": 0,
        "ResolutionDepth": 0,
        "FontSmoothing": false,
        "AutoDownloadProcess": false
    }
}
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Robots/$entity",
    "LicenseKey": "fc157179-3724-4bb0-acd2-8261bef82d01",
    "MachineName": "CAPETRINA",
    "MachineId": 15,
    "Name": "Gustavee",
    "Username": "uipath\\john.smith",
    "ExternalName": null,
    "Description": null,
    "Type": "Development",
    "HostingType": "Standard",
    "ProvisionType": "Manual",
    "Password": null,
    "CredentialStoreId": null,
    "UserId": 45,
    "Enabled": true,
    "CredentialType": null,
    "RobotEnvironments": "",
    "IsExternalLicensed": false,
    "LimitConcurrentExecution": false,
    "Id": 216,
    "ExecutionSettings": {
        "ResolutionHeight": 0,
        "ResolutionDepth": 0,
        "FontSmoothing": false,
        "AutoDownloadProcess": false
    }
}

Retrieving all robots that can execute a specific process

The following example makes a request to the /odata/Robots/UiPath.Server.Configuration.OData.GetRobotsForProcess. It enables you to identify, on the fly, which Robots can execute the package with the input_output_arguments_example id.

GET

https://{yourDomain}/odata/Robots/UiPath.Server.Configuration.OData.GetRobotsForProcess(processId='input_output_arguments_example')

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
  "@odata.context": "https://{yourDomain}/odata/$metadata#Robots",
  "@odata.count": 2,
  "value": [
    {
      "LicenseKey": null,
      "MachineName": "DESKTOP-ASBD",
      "MachineId": 129,
      "Name": "Stan",
      "Username": "Alex",
      "Description": null,
      "Version": null,
      "Type": "Unattended",
      "HostingType": "Standard",
      "Password": null,
      "RobotEnvironments": "doc_env,a_invoke_env,Group1",
      "Id": 759,
      "ExecutionSettings": null
    },
    {
      "LicenseKey": null,
      "MachineName": "Doc",
      "MachineId": 1066,
      "Name": "DocBot",
      "Username": "uipath\\documentation",
      "Description": null,
      "Version": "18.3.0.558",
      "Type": "NonProduction",
      "HostingType": "Standard",
      "Password": null,
      "RobotEnvironments": "doc_env",
      "Id": 1684,
      "ExecutionSettings": null
    }
  ]
}
{
  "@odata.context": "https://{yourDomain}/odata/$metadata#Robots",
  "@odata.count": 2,
  "value": [
    {
      "LicenseKey": null,
      "MachineName": "DESKTOP-ASBD",
      "MachineId": 129,
      "Name": "Stan",
      "Username": "Alex",
      "Description": null,
      "Version": null,
      "Type": "Unattended",
      "HostingType": "Standard",
      "Password": null,
      "RobotEnvironments": "doc_env,a_invoke_env,Group1",
      "Id": 759,
      "ExecutionSettings": null
    },
    {
      "LicenseKey": null,
      "MachineName": "Doc",
      "MachineId": 1066,
      "Name": "DocBot",
      "Username": "uipath\\documentation",
      "Description": null,
      "Version": "18.3.0.558",
      "Type": "NonProduction",
      "HostingType": "Standard",
      "Password": null,
      "RobotEnvironments": "doc_env",
      "Id": 1684,
      "ExecutionSettings": null
    }
  ]
}

Retrieving robot logs according to the robot name

The following example enables you to view Robot logs for the Robot named DocBot.

GET

https://{yourDomain}/odata/RobotLogs?$top=100&$skip=200&$filter=RobotName eq 'DocBot'

Request headers

Key	Value
Authorization	Bearer

Response code

200 OK

Response body

{
    "@odata.context": "https://{yourDomain}/odata/$metadata#RobotLogs",
    "@odata.count": 202,
    "value": [
        {
            "Level": "Info",
            "WindowsIdentity": "UIPATH\\john.smith",
            "ProcessName": "TestingSequence_DOC",
            "TimeStamp": "2019-10-14T13:55:18.2473626Z",
            "Message": "TestingSequence_DOC execution started",
            "JobKey": "e49c0012-ee01-45e4-884c-0ce1f2aa6fbb",
            "RawMessage": "{\r\n  \"message\": \"TestingSequence_DOC execution started\",\r\n  \"level\": \"Information\",\r\n  \"logType\": \"Default\",\r\n  \"timeStamp\": \"2019-10-14T13:55:18.2473626+00:00\",\r\n  \"fingerprint\": \"972a32c3-95d9-4264-ae5d-af589bf4f0b5\",\r\n  \"windowsIdentity\": \"UIPATH\\\\petrina.calota\",\r\n  \"machineName\": \"LAPTOP-IN7198N3\",\r\n  \"processName\": \"TestingSequence_DOC\",\r\n  \"processVersion\": \"1.1.7024.37929\",\r\n  \"jobId\": \"e49c0012-ee01-45e4-884c-0ce1f2aa6fbb\",\r\n  \"robotName\": \"G\",\r\n  \"machineId\": 229978,\r\n  \"organizationUnitId\": 67543,\r\n  \"fileName\": \"Main\"\r\n}",
            "RobotName": "DocBot",
            "MachineId": 229978,
            "Id": 0
        },
        {
            "Level": "Info",
            "WindowsIdentity": "UIPATH\\john.smith",
            "ProcessName": "TestingSequence_DOC",
            "TimeStamp": "2019-10-14T13:57:21.4985672Z",
            "Message": "TestingSequence_DOC execution ended",
            "JobKey": "e49c0012-ee01-45e4-884c-0ce1f2aa6fbb",
            "RawMessage": "{\r\n  \"message\": \"TestingSequence_DOC execution ended\",\r\n  \"level\": \"Information\",\r\n  \"logType\": \"Default\",\r\n  \"timeStamp\": \"2019-10-14T13:57:21.4985672+00:00\",\r\n  \"fingerprint\": \"e973b4f2-deec-4290-978b-3a8af0769b35\",\r\n  \"windowsIdentity\": \"UIPATH\\\\petrina.calota\",\r\n  \"machineName\": \"LAPTOP-IN7198N3\",\r\n  \"processName\": \"TestingSequence_DOC\",\r\n  \"processVersion\": \"1.1.7024.37929\",\r\n  \"jobId\": \"e49c0012-ee01-45e4-884c-0ce1f2aa6fbb\",\r\n  \"robotName\": \"G\",\r\n  \"machineId\": 229978,\r\n  \"organizationUnitId\": 67543,\r\n  \"totalExecutionTimeInSeconds\": 123,\r\n  \"totalExecutionTime\": \"00:02:03\",\r\n  \"fileName\": \"Main\"\r\n}",
            "RobotName": "DocBot",
            "MachineId": 229978,
            "Id": 0
        }
  ]
}
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#RobotLogs",
    "@odata.count": 202,
    "value": [
        {
            "Level": "Info",
            "WindowsIdentity": "UIPATH\\john.smith",
            "ProcessName": "TestingSequence_DOC",
            "TimeStamp": "2019-10-14T13:55:18.2473626Z",
            "Message": "TestingSequence_DOC execution started",
            "JobKey": "e49c0012-ee01-45e4-884c-0ce1f2aa6fbb",
            "RawMessage": "{\r\n  \"message\": \"TestingSequence_DOC execution started\",\r\n  \"level\": \"Information\",\r\n  \"logType\": \"Default\",\r\n  \"timeStamp\": \"2019-10-14T13:55:18.2473626+00:00\",\r\n  \"fingerprint\": \"972a32c3-95d9-4264-ae5d-af589bf4f0b5\",\r\n  \"windowsIdentity\": \"UIPATH\\\\petrina.calota\",\r\n  \"machineName\": \"LAPTOP-IN7198N3\",\r\n  \"processName\": \"TestingSequence_DOC\",\r\n  \"processVersion\": \"1.1.7024.37929\",\r\n  \"jobId\": \"e49c0012-ee01-45e4-884c-0ce1f2aa6fbb\",\r\n  \"robotName\": \"G\",\r\n  \"machineId\": 229978,\r\n  \"organizationUnitId\": 67543,\r\n  \"fileName\": \"Main\"\r\n}",
            "RobotName": "DocBot",
            "MachineId": 229978,
            "Id": 0
        },
        {
            "Level": "Info",
            "WindowsIdentity": "UIPATH\\john.smith",
            "ProcessName": "TestingSequence_DOC",
            "TimeStamp": "2019-10-14T13:57:21.4985672Z",
            "Message": "TestingSequence_DOC execution ended",
            "JobKey": "e49c0012-ee01-45e4-884c-0ce1f2aa6fbb",
            "RawMessage": "{\r\n  \"message\": \"TestingSequence_DOC execution ended\",\r\n  \"level\": \"Information\",\r\n  \"logType\": \"Default\",\r\n  \"timeStamp\": \"2019-10-14T13:57:21.4985672+00:00\",\r\n  \"fingerprint\": \"e973b4f2-deec-4290-978b-3a8af0769b35\",\r\n  \"windowsIdentity\": \"UIPATH\\\\petrina.calota\",\r\n  \"machineName\": \"LAPTOP-IN7198N3\",\r\n  \"processName\": \"TestingSequence_DOC\",\r\n  \"processVersion\": \"1.1.7024.37929\",\r\n  \"jobId\": \"e49c0012-ee01-45e4-884c-0ce1f2aa6fbb\",\r\n  \"robotName\": \"G\",\r\n  \"machineId\": 229978,\r\n  \"organizationUnitId\": 67543,\r\n  \"totalExecutionTimeInSeconds\": 123,\r\n  \"totalExecutionTime\": \"00:02:03\",\r\n  \"fileName\": \"Main\"\r\n}",
            "RobotName": "DocBot",
            "MachineId": 229978,
            "Id": 0
        }
  ]
}

Note:

GET requests for Robot logs stored using Elasticsearch only retrieve the first 10000 entries. This is due to an Elasticsearch limitation, and it does not occur if you are using SQL. Using $top and $skip parameters which go beyond the 10,000 limit returns the following error message: "Depth of pagination is limited in Elasticsearch by the max_result_window index setting. Make sure skip + take is lower than 10000". Only the following condition-verb combinations are supported when parameterizing requests for Robot logs stored using Elasticsearch: RobotName eq, JobKey eq, MachineId eq, Level ge, TimeStamp gt.

Editing robot information

The following example changes the type and name of the Robot with the 749 Id, and modifies its execution settings configuration. Remember to put the X-UIPATH-OrganizationUnitId in the request header, and the Robot Id and the machine name in the request body.

Note:

When making PUT requests to the Robots endpoint please take into account the following:

the Robot username and password are not updated when you send the same username and a null or empty password.
if a new username is sent with a null or empty password, the Robot credentials are updated and the new username is used.

PUT

https://{yourDomain}/odata/Robots(749)

Request headers

Key	Value
Authorization	Bearer
X-UIPATH-OrganizationUnitId	The container folder ID. For example, `36886`.

Request body

{
  "LicenseKey": "8ec4t984-b2d7-44f2-b5be-0a64ee9a487b",
  "MachineName": "MBOBOC",
  "Name": "DocBot",
  "Type": "Development",
  "Id": 749,
  "Username": "UIPATH\\JustAnotherRobot",
  "ExecutionSettings":{
        "TracingLevel":"Information",
        "StudioNotifyServer":true,
        "LoginToConsole":false,
        "ResolutionWidth":0,
        "ResolutionHeight":0,
        "ResolutionDepth":0,
        "FontSmoothing":false,
        "AutoDownloadProcess":false
    }
}
{
  "LicenseKey": "8ec4t984-b2d7-44f2-b5be-0a64ee9a487b",
  "MachineName": "MBOBOC",
  "Name": "DocBot",
  "Type": "Development",
  "Id": 749,
  "Username": "UIPATH\\JustAnotherRobot",
  "ExecutionSettings":{
        "TracingLevel":"Information",
        "StudioNotifyServer":true,
        "LoginToConsole":false,
        "ResolutionWidth":0,
        "ResolutionHeight":0,
        "ResolutionDepth":0,
        "FontSmoothing":false,
        "AutoDownloadProcess":false
    }
}

Response code

200 OK

Deleting robots

Deleting a single robot

To delete a specific Robot perform a DELETE request to the odata/Robots({robot_id}) endpoint.

DELETE

https://{yourDomain}/odata/Robots(79)

Request headers

Key	Value
Authorization	Bearer

Response code

204 No Content

Deleting several robots

To delete multiple Robots at the same time perform a POST request to the /Robots/UiPath.Server.Configuration.OData.DeleteBulk endpoint.

POST

https://{yourDomain}/odata/Robots/UiPath.Server.Configuration.OData.DeleteBulk

Request headers

Key	Value
Authorization	Bearer

Request body

{
    "robotIds": [119, 120]
}
{
    "robotIds": [119, 120]
}

Response code

204 No Content

Updating the password for your own unattended robot

Calling the endpoint below updates your own unattended robot's password, by inputting your user ID (for example, let's say your user ID is 88). This operation does not require Edit permissions on Users.

Note:

If you want to update the password of a different robot, make a PUT request to the same endpoint, using the ID of the respective user.

PATCH

https://{yourDomain}/odata/Users(88)

Request headers

Key	Value
Authorization	Bearer

Request body

{
"UnattendedRobot": 
   {
    "Password": "newUnattendedRobotP@ss"
    }
}
{
"UnattendedRobot": 
   {
    "Password": "newUnattendedRobotP@ss"
    }
}

Response code

200 OK

On this page

Retrieving robot statuses
According to its ID
According to its name
Retrieving robot information according to its state: Example 1
Request headers
Response code
Response body
Retrieving robot information according to its state: Example 2
Request headers
Response code
Response body
Retrieving robot information according to its ID
Request headers
Response code
Response body
Retrieving all robots that can execute a specific process
Request headers
Response code
Response body
Retrieving robot logs according to the robot name
Request headers
Response code
Response body
Editing robot information
Request headers
Request body
Response code
Deleting robots
Deleting a single robot
Deleting several robots
Updating the password for your own unattended robot
Request headers
Request body
Response code

Was this page helpful?

PREVIOUSQueue retention policy requests

NEXTRoles requests

Retrieving robot statuses​

According to its ID​

Request headers​

Response code​

Response body​

According to its name​

Request headers​

Response code​

Response body​

Retrieving robot information according to its state: Example 1​

Request headers​

Response code​

Response body​

Retrieving robot information according to its state: Example 2​

Request headers​

Response code​

Response body​

Retrieving robot information according to its ID​

Request headers​

Response code​

Response body​

Retrieving all robots that can execute a specific process​

Request headers​

Response code​

Response body​

Retrieving robot logs according to the robot name​

Request headers​

Response code​

Response body​

Editing robot information​

Request headers​

Request body​

Response code​

Deleting robots​

Deleting a single robot​

Request headers​

Response code​

Deleting several robots​

Request headers​

Request body​

Response code​

Updating the password for your own unattended robot​

Request headers​

Request body​

Response code​

Was this page helpful?

Retrieving robot statuses

According to its ID

Request headers

Response code

Response body

According to its name

Request headers

Response code

Response body

Retrieving robot information according to its state: Example 1

Request headers

Response code

Response body

Retrieving robot information according to its state: Example 2

Request headers

Response code

Response body

Retrieving robot information according to its ID

Request headers

Response code

Response body

Retrieving all robots that can execute a specific process

Request headers

Response code

Response body

Retrieving robot logs according to the robot name

Request headers

Response code

Response body

Editing robot information

Request headers

Request body

Response code

Deleting robots

Deleting a single robot

Request headers

Response code

Deleting several robots

Request headers

Request body

Response code

Updating the password for your own unattended robot

Request headers

Request body

Response code