Search and Filter transactions API

HTTP method and URI path

POST  /api/<monitor_id>/explainability/payload/search

monitor_id identifies the monitor ID.

Along with this search query, you can use the following optional arguments:

model_version - filters results based on the version number of the deployed model. The default value is 1.
limit - sets the number of results that the search displays. The default value is 500.

Standard headers

Use the following standard HTTP headers with this request:

Content-Type: application/json
Authorization: <Bearer token>

Required authorization

The user ID associated with the token which is specified in the request header must be assigned with one of the following roles:

sysadm
mladm
api user (only if the monitor is created by the user)

Request body

The request content contains a JSON object. For descriptions of the fields, see the following table:

Table 1. Supported parameters for the Payload Search API
Parameter	Type	Required or Optional	Description

name	String	Required	Indicates the name of the field.
op	String	Required	Indicates the operation performed by the fields. The values are: `EQ` - equal to `GT` - greater than `LT` - lesser than `LIKE` - searches for a matched value for the specified field
base_value	String	Required	Indicates the value that the field will be filtered with.

Following are the examples:

When the request body is empty. To retrieve all transactions with the default model version and limit:
```
[
]
```
When the request body has a value, you can also specify a single field only if you change the name of the field:
```
[
{
    "name" : "all",
    "op" : "like",
    "base_value" : "2023"
}
]
```

When the request body has a time range for the transactions:


[
{
    "name" : "transaction_time",
    "op" : "gt",
    "base_value" : "2023-01-01"
},
{
    "name" : "transaction_time",
    "op" : "lt",
    "base_value" : "2023-06-01"
}
]

When the request body has a value to be searched for a specific criteria. For example, retrieve the transactions that has an input feature as "Sepal.Length" value equal to 5.0:
```
[
{
		"name": "Sepal.Length"
		"op": "eq",
		"base_value":"5.0"
}
]
```

Expected response

On completion, the service returns an HTTP response, which includes a status code that indicates whether the request is complete. Status code 200 indicates that the request is complete.

Example of a response from a successful request:


[
{
        "content": {
            "request": {
                "fields": [
                    "Sepal.Length",
                    "Sepal.Width",
                    "Petal.Length",
                    "Petal.Width"
                ],
                "values": [
                    [
                        8.6,
                        2.3,
                        3.4,
                        6.7
                    ]
                ]
            },
            "response": {
                "fields": [
                    "probability(setosa)",
                    "probability(versicolor)",
                    "probability(virginica)"
                ],
                "values": [
                    [
                        0.1,
                        0.6,
                        0.9
                    ]
                ]
            }
        },
        "deployment_id": "c4adaf92-f591-41d1-86b6-bdb6544649af",
        "model_version": "2",
        "model_version_id": "222222",
        "payload_id": "3969ac05-7461-4015-95cc-fdcf345764db",
        "subscription_id": "943446d0-3e55-431a-be6b-38f5bdf7267e",
        "transaction_id": "7000",
        "transaction_time": "2024-01-22 16:23:15"
    }
]

The response content contains a JSON object. See the following table for description of the fields.

Table 2. Response field descriptions
Parameter	Description
content	Indicates the collection of values that represent the input features that the request uses for prediction and the output features received from the prediction. It generally includes the request and the response that consists of: `field` - name of the features. `value` - the configured value of the feature. Example: `"request": { "fields": [ "Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width" ], "values": [ [ 8.6, 2.3, 3.4, 6.7 ] ] }, Sample response looks like below: "response": { "fields": [ "probability(setosa)", "probability(versicolor)", "probability(virginica)" ], "values": [ [ 0.1, 0.6, 0.9 ] ] }`
deployment_id	Indicates the unique ID of the deployment.
model_version	Indicates the version of the model.
model_version_id	Indicates the ID that is associated with a specific version of the model.
payload_id	Indicates the unique ID of the payload.
subscription_id	Indicates the unique ID of the monitor.
transaction_id	Indicates the unique ID of the transaction.
transaction_time	Indicates the time when the transaction was created.

HTTP status codes

For a successful request, the service returns the HTTP status code 200 and provides the response body, as described in the Expected response section.

For unsuccessful requests, the service returns the status codes that are described in the following table:

Table 3. HTTP status code descriptions
HTTP status code	Possible causes
404	The monitor does not exist.
500	Failed to get payloads for the monitor. For details about the error, check the logs.