# Transactions requests

> :::note
Queue items can only be processed by Robots. For example, making a POST request to the `/odata/Queues/UiPathODataSvc.StartTransaction` endpoint requires information which is only available to the Robot.
:::

:::note
Queue items can only be processed by Robots. For example, making a POST request to the `/odata/Queues/UiPathODataSvc.StartTransaction` endpoint requires information which is only available to the Robot.
:::

## Viewing the history of an item

The following call enables you to view all the actions that a specific queue item went through.

GET

`https://{yourDomain}/odata/QueueItemEvents/UiPath.Server.Configuration.OData.GetQueueItemEventsHistory(queueItemId=1050203)?$orderby=Timestamp&$top=10`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#QueueItemEvents",
    "@odata.count": 5,
    "value": [
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T16:02:59.09Z",
            "Action": "Create",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "New",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 18276
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T18:15:04.46Z",
            "Action": "Status",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 20333
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T18:15:05.07Z",
            "Action": "Edit",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 20334
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-07T18:15:05.507Z",
            "Action": "Edit",
            "Data": null,
            "UserId": 910,
            "UserName": "DocBot",
            "Status": "Failed",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "ReviewerUserName": null,
            "Id": 20335
        },
        {
            "QueueItemId": 1050203,
            "Timestamp": "2018-03-08T10:47:40.463Z",
            "Action": "Edit",
            "Data": null,
            "UserId": 583,
            "UserName": "admin",
            "Status": "Failed",
            "ReviewStatus": "None",
            "ReviewerUserId": 583,
            "ReviewerUserName": "admin",
            "Id": 21240
        }
    ]
}
```

## Retrieving the average execution time for a specific queue

The following request enables you to see the average execution time of items in an indicated queue.

:::note
This type of request can only be filtered according to the queue name or description, and not queue id.
:::

GET

`https://{yourDomain}/odata/QueueProcessingRecords/UiPathODataSvc.RetrieveQueuesProcessingStatus?$filter=QueueDefinitionName eq 'DocQueue'`

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#Collection(UiPath.Core.Model.Queues.QueueProcessingStatus)",
    "@odata.count": 1,
    "value": [
        {
            "ItemsToProcess": 682,
            "ItemsInProgress": 0,
            "QueueDefinitionId": 188,
            "QueueDefinitionName": "DocQueue",
            "QueueDefinitionDescription": null,
            "QueueDefinitionAcceptAutomaticallyRetry": true,
            "QueueDefinitionMaxNumberOfRetries": 5,
            "QueueDefinitionEnforceUniqueReference": false,
            "ProcessingMeanTime": 2.15,
            "SuccessfulTransactionsNo": 0,
            "ApplicationExceptionsNo": 0,
            "BusinessExceptionsNo": 883,
            "SuccessfulTransactionsProcessingTime": 0,
            "ApplicationExceptionsProcessingTime": 0,
            "BusinessExceptionsProcessingTime": 2.15,
            "TotalNumberOfTransactions": 883,
            "LastProcessed": "2018-03-07T18:20:29.3833333Z"
        }
    ]
}
```

## Changing the reviewer of a Queue Item

The following example enables you to change the reviewer of the failed transaction item with the 1050200 Id.

:::note
The value of the `RowVersion` parameter changes each time an update is made to a queue item. To retrieve this information, perform a GET call on the `/odata/QueueItems()` endpoint, such as `https://{yourDomain}/odata/QueueItems(1050200)`.
:::

POST

`https://{yourDomain}/odata/QueueItems/UiPathODataSvc.SetItemReviewer`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

### Request body

```
{
    "queueItems": [{
        "Id": 1050200, 
        "RowVersion":"AAAAAABDIK8="
    }], 
    "userId": 583
}
```

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#UiPath.Application.Dto.BulkOperationResponseDto_1OfInt64",
    "Success": true,
    "Message": null,
    "FailedItems": []
}
```

## Retrieving Queue Items with an indicated review status

This example enables you to extract the first two queue items that have a Revision status set to In Review.

GET

`https://{yourDomain}/odata/QueueItems?$filter=ReviewStatus eq 'InReview'&$top=2`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#QueueItems",
    "@odata.count": 3,
    "value": [
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "Failed",
            "ReviewStatus": "InReview",
            "ReviewerUserId": 583,
            "Key": "e4760d27-a76d-4469-b7e6-fbda2f732b10",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": "BusinessException",
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T18:14:56.633Z",
            "EndProcessing": "2018-03-07T18:14:58.723Z",
            "SecondsInPreviousAttempts": 2,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Gets a specified credential by using a provided AssetName, and returns a username and a secure password.\"}}",
            "CreationTime": "2018-03-07T16:02:57.547Z",
            "Progress": null,
            "RowVersion": "AAAAAABDFiU=",
            "Id": 1050199,
            "ProcessingException": {
                "Reason": "authentication",
                "Details": null,
                "Type": "BusinessException",
                "AssociatedImageFilePath": null,
                "CreationTime": "2018-03-07T18:14:58.723Z"
            },
            "SpecificContent": {
                "Description": "Gets a specified credential by using a provided AssetName, and returns a username and a secure password."
            },
            "Output": null
        },
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "Failed",
            "ReviewStatus": "InReview",
            "ReviewerUserId": 583,
            "Key": "e90e8067-50fc-407a-9678-eede311f815a",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": "BusinessException",
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T18:14:54.85Z",
            "EndProcessing": "2018-03-07T18:14:57.103Z",
            "SecondsInPreviousAttempts": 2,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Gets a specified asset by using a provided AssetName. If the asset is not global, it must be assigned to the local robot in order to be retrieved.\"}}",
            "CreationTime": "2018-03-07T16:02:57.287Z",
            "Progress": null,
            "RowVersion": "AAAAAABDFiY=",
            "Id": 1050198,
            "ProcessingException": {
                "Reason": "authentication",
                "Details": null,
                "Type": "BusinessException",
                "AssociatedImageFilePath": null,
                "CreationTime": "2018-03-07T18:14:57.103Z"
            },
            "SpecificContent": {
                "Description": "Gets a specified asset by using a provided AssetName. If the asset is not global, it must be assigned to the local robot in order to be retrieved."
            },
            "Output": null
        }
    ]
}
```

## Adding a Queue Item

The example below enables us to add an item to the "DocQueue" queue, with a high priority, defer and due dates, and two arguments with values. All items added like this have the New status, just like the [Add Queue Item activity](https://activities.uipath.com/docs/add-queue-item).

Please note that the `SpecificContent` parameter should be populated only with primitive values.

POST

`https://{yourDomain}/odata/Queues/UiPathODataSvc.AddQueueItem`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

### Request body

```
{
    "itemData": {
        "Priority": "High",
        "DeferDate": "2018-03-21T13:42:27.654Z",
        "DueDate": "2018-03-25T13:42:27.654Z",
        "Name": "DocQueue",
        "SpecificContent": {
            "Email": "obrian@uipath.com", 
            "Name": "O'Brian"
        }
    }
}
```

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#queueItem/$entity",
    "QueueDefinitionId": 188,
    "OutputData": null,
    "Status": "New",
    "ReviewStatus": "None",
    "ReviewerUserId": null,
    "Key": "e9cb2205-0232-4b99-9556-52dc2e686663",
    "Reference": null,
    "ProcessingExceptionType": null,
    "DueDate": "2018-03-25T13:42:27.654Z",
    "Priority": "High",
    "DeferDate": "2018-03-21T13:42:27.654Z",
    "StartProcessing": null,
    "EndProcessing": null,
    "SecondsInPreviousAttempts": 0,
    "AncestorId": null,
    "RetryNumber": 0,
    "SpecificData": "{\"DynamicProperties\":{\"Email\":\"obrian@uipath.com\",\"Name\":\"O'brian\"}}",
    "CreationTime": "2018-03-21T15:31:27.2699068Z",
    "Progress": null,
    "RowVersion": "AAAAAABDGLk=",
    "Id": 1050947,
    "ProcessingException": null,
    "SpecificContent": {
        "Email": "obrian@uipath.com",
        "Name": "O'Brian"
    },
    "Output": null
}}
```

## Adding multiple Queue Items

:::important
If you are assigned to multiple folders, your request must contain an HTTP header providing either the `FolderId` or `FolderPath` of the desired queue. See [here](https://docs.uipath.com/orchestrator/standalone/2024.10/api-guide/building-api-requests#building-api-requests) for details. If not included, the request fails with the following error: `An organization unit is required for this action.`
:::

The examples below enables us to add multiple items at the same time to the "DocTest" queue that has been configured to only allow unique references. Once the items have been added, they all have the **New** status.

It is recommended to specify the data type for Specific Data content. For example, if the **Name** field contains data of type String, then you should add an extra key:value pair using the following syntax `"Name@odata.type": "#string"`. See the examples below.

The first example is successful, while the latter fails because the items lack references which are required for unique-reference queues.

There are two upload strategies one can use when adding multiple queue items:

* `AllOrNothing` - Adds queue items only if an error is not encountered. Otherwise, it does not insert anything and returns the row where the error occurred.
* `ProcessAllIndependently` - Adds all your items and returns a list of all those that failed.
  :::note
  Failed requests return 200 OK, as the failed items are returned in the body of the response, as you can see in the second example. The only requests that do not return 200 OK are those in which the input parameters are incorrect.
  :::

### Successful request

POST

`https://{yourDomain}/odata/Queues/UiPathODataSvc.BulkAddQueueItems`

#### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

#### Request body

```
{
    "queueName": "DocTest",
    "commitType": "AllOrNothing",
    "queueItems": [{
            "Priority": "High",
            "SpecificContent": {
                "Name": "rêvé",
                "Name@odata.type": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
            "Reference": "ref4"
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "même",
                "Name@odata.type": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
            "Reference": "ref5"
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "Žao",
                "Name@odata.type": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
            "Reference": "ref6"
        }
    ]
}
```

#### Response code

200 OK

#### Response body

```
{
  "@odata.context": "https://{yourDomain}/odata/$metadata#UiPath.Application.Dto.BulkOperationResponseDto_1OfFailedQueueItemDto",
  "Success": true,
  "Message": null,
  "FailedItems": []
}
```

### Failed request

POST

`https://{yourDomain}/odata/Queues/UiPathODataSvc.BulkAddQueueItems`

#### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

#### Request body

```
{
    "queueName": "DocTest",
    "commitType": "AllOrNothing",
    "queueItems": [{
            "Priority": "High",
            "SpecificContent": {
                "Name": "rêvé",
                "Name@odata.type": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "même",
                "Name@odata.type": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
        },
        {
            "Priority": "High",
            "SpecificContent": {
                "Name": "Žao",
                "Name@odata.type": "#String"
            },
            "DeferDate": "2019-03-14T12:20:13.290Z",
            "DueDate": "2019-03-14T12:20:13.290Z",
        }
    ]
}
```

#### Response code

200 OK

#### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#UiPath.Application.Dto.BulkOperationResponseDto_1OfFailedQueueItemDto",
    "Success": false,
    "Message": "Some items have not been inserted.",
    "FailedItems": [{
        "Ordinal": 1,
        "ErrorCode": "TransactionReferenceRequired",
        "ErrorMessage": "Error creating Transaction. Reference is required for Unique Reference Queues."
    }]
}
```

## Retrieving transactions according to their status and robot ID

The example below queries the Orchestrator database for the first 10 queue items with the **In Progress** status that were processed by the Robot with the 749 Id. Lastly, the Robot information is expanded. Please note that the Response was truncated.

GET

`https://{yourDomain}/odata/QueueItems?$top=10&$expand=Robot&$filter=Status eq 'InProgress' and Robot/Id eq 749`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#QueueItems",
    "@odata.count": 1752,
    "value": [
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "Key": "1c632cc1-44ab-4624-bace-6fbb5fd1c0cd",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": null,
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T15:05:05.113Z",
            "EndProcessing": null,
            "SecondsInPreviousAttempts": 0,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Checks if Stop was triggered in UiPath Orchestrator.\"}}",
            "CreationTime": "2018-03-05T18:39:16.06Z",
            "Progress": null,
            "RowVersion": "AAAAAABC3aA=",
            "Id": 1048065,
            "ProcessingException": null,
            "SpecificContent": {
                "Description": "Checks if Stop was triggered in UiPath Orchestrator."
            },
            "Output": null,
            "Robot": {
                "LicenseKey": null,
                "MachineName": "MBOBOC",
                "Name": "DocBot",
                "Username": "UIPATH\\MADALINA.BOBOC",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "",
                "Id": 749,
                "ExecutionSettings": null
            }
        },
        {
            "QueueDefinitionId": 188,
            "OutputData": null,
            "Status": "InProgress",
            "ReviewStatus": "None",
            "ReviewerUserId": null,
            "Key": "7dfa834b-8398-476e-bd18-b0fa51d4ddf6",
            "Reference": "ActivityDescription",
            "ProcessingExceptionType": null,
            "DueDate": null,
            "Priority": "High",
            "DeferDate": null,
            "StartProcessing": "2018-03-07T15:05:04.503Z",
            "EndProcessing": null,
            "SecondsInPreviousAttempts": 0,
            "AncestorId": null,
            "RetryNumber": 0,
            "SpecificData": "{\"DynamicProperties\":{\"Description\":\"Sets the status of a transaction item to Failed or Successful.\"}}",
            "CreationTime": "2018-03-05T18:39:15.627Z",
            "Progress": null,
            "RowVersion": "AAAAAABC3Z8=",
            "Id": 1048064,
            "ProcessingException": null,
            "SpecificContent": {
                "Description": "Sets the status of a transaction item to Failed or Successful."
            },
            "Output": null,
            "Robot": {
                "LicenseKey": null,
                "MachineName": "MBOBOC",
                "Name": "DocBot",
                "Username": "UIPATH\\MADALINA.BOBOC",
                "Description": null,
                "Type": "NonProduction",
                "Password": null,
                "RobotEnvironments": "",
                "Id": 749,
                "ExecutionSettings": null
            }
        }
    ]
}
```

## Retrieving comments for a specific item

The example below displays all the comments of the queue item with the 1050204 Id, in ascending order of creation.

GET

`https://{yourDomain}/odata/QueueItemComments/UiPath.Server.Configuration.OData.GetQueueItemCommentsHistory(queueItemId=1050204)?$orderby=CreationTime%20desc`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |

### Response code

200 OK

### Response body

```
{
    "@odata.context": "https://{yourDomain}/odata/$metadata#QueueItemComments",
    "@odata.count": 2,
    "value": [
        {
            "Text": "needs review asap",
            "QueueItemId": 1050204,
            "CreationTime": "2018-03-08T13:41:49.167Z",
            "UserId": 583,
            "UserName": "admin",
            "Id": 320
        },
        {
            "Text": "fixed. excel hiccup.",
            "QueueItemId": 1050204,
            "CreationTime": "2018-03-08T13:46:48.613Z",
            "UserId": 901,
            "UserName": "dragomirmir",
            "Id": 321
        }
    ]
}
```