---
title: "REST - Search"
canonical: "https://help.agiloft.com/space/HELP/43717730/REST+-+Search"
format: markdown
---
> Macro (anchor)

The EWSearch operation runs a saved search or an ad hoc query on the specified table. It returns the number of records found, and for each record, it returns an encoded set of field values.

- **Returns**: the number of records found, and for each record, it returns an encoded set of field values. If pagination is being used, the number of records is in the context of the current page and the specified page size. Each set of field values includes the ID and the fields used to define record ownership, such as `requester_login` in the examples below.
- **Supported Content-Types**: x-www-form-urlencoded
- Accepts a URL with URL-encoded parameters and record data. For more information about general URL conventions, see [REST Interface](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715778).
- Additionally, the label of the saved search or an ad hoc query may be included in the call. This operation allows retrieval of results page by page (pagination) using "page" and "limit" parameters. Queries in the URL may use operators without %N encoding, such as `>`, `>=`, etc.
- Additionally, to include more fields in the encoded sets being returned, a series of 'field' parameters may be specified using the logical name of each field. Logical field names can be found in the Field Wizard.

## Ad Hoc Searches

In contrast to saved searches, ad hoc searches are limited to run-time queries using the `query` clause. They can also be used within Workato queries. An example of such a REST query is shown below using the conditions `&query=summary~='test'%26%26priority=3`:

`https://localhost:8080/ewws/EWSearch?$KB=Demo&$table=case&$login=admin&$password=qwerty&$lang=en&query=summary~='test'%26%26priority=3`

To search on multiple fields, use a single `query` parameter that contains all the fields. Connect each field using %26%26, which equates to "&&" or `and`, or using %7C%7C, which equates to "||" or `or`. Surround each search value in single quotes, and if a field label contains spaces, surround that field label in single quotes as well. Empty fields can be designated with null.

For example: `query=Approver%3D'Denise%20Teller'%26%26'Date Previous Status Change'>'Aug 24 2021 00:00'`

> ✅ The following operators are supported:
> ✅ 
> ✅ - Equals: = encoded as %3D
> ✅ - Does not equal: != encoded as %21%3D
> ✅ - Contains: ~= encoded as %7E%3D
> ✅ - And: && encoded as %26%26
> ✅ - Or: || encoded as %7C%7C
> ✅ - Less than: < encoded as %3C
> ✅ - Less than or equal to: <= encoded as %3C%3D
> ✅ - Greater than: > encoded as %3E
> ✅ - Greater than or equal to: >= encoded as %3E%3D

# Examples

Below are some examples of how to use the API.

#### Query Parameters

| **Param** | **Desc** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| **KB** | The name of your KB | string | Required | Can be found in the top right-hand corner of the KB |
| **table** | The table that holds the file field | string | Required | Uses logical table name |
| **login** | The username you use to log in to your KB | string | Required |  |
| **password** | The password that corresponds with the login value | string | Required |  |
| **lang** | The language code | string | Optional | Two-letter codes only. Valid values are: ?<br>Default is: ? |
| **query** | The field and search you're looking for | string | Required | If you wanted to search for records with a Status of Closed, Status=closed or similar |
| **field** | The name of the field you want to search | string | Required |  |
| **field** | The ID of the field you want to search | string | Required |  |

#### applications/JSON

This uses the following information.

| **Param** | **Desc** |
| --- | --- |
| field | id |
| field | id |
| field | id |
| field | id |
| lang | en |

#### JSON

```
{
  "field": [
    "id",
    "summary"
  ],
  "query": "summary=test"
}
```

#### cURL

```
curl --location 'http://localhost:8080/ewws/alrest/CLM Template/case/search?lang=en' \
--data '{
  "field": [
    "id",
    "summary"
  ],
  "query": "summary=test"
}'
```

#### cURL

```
curl --location 'http://localhost:8080/ewws/EWSearch' \
--data-urlencode '%24KB=CLM Template' \
--data-urlencode '%24table=case' \
--data-urlencode '%24login=admin' \
--data-urlencode '%24password=qwerty' \
--data-urlencode '%24lang=en' \
--data-urlencode 'query=summary=test' \
--data-urlencode 'field=id' \
--data-urlencode 'field=summary'
```

#### Additional Urlencoded Example, Example 1

Assume an instance of Agiloft is available on localhost, port 8080 and the knowledgebase is called 'Demo'. List the Service Request records that correspond to the saved search 'C: Status is Closed'. Additionally, only return those that have High priority.

The following request is issued: 

```javascript
https://localhost:8080/ewws/EWSearch?$KB=Demo&$login=admin&$password=qwerty&$table=helpdesk_case&$lang=en&search=C%3A%20Status%20is%20Closed&query=priority%3DHigh
```

If there are no records found, the following result will be returned: 

```javascript
 EWREST_id_length = '0';
```

The following result will be returned in the case of four records being found. 

> ⚠️ If no return fields are specified in the request, it will return the ID, type fields and requester login field, based on the [record ownership](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43718158) defined for the Service Request table, based on the permissions definition for the Service Request table.

```javascript
EWREST_length = '4';
EWREST_login_0='ewsystem';
EWREST_type_0='helpdesk_case';
EWREST_id_0='318';
EWREST_login_1='ewsystem';
EWREST_type_1='helpdesk_case';
EWREST_id_1='151';
EWREST_login_2='ewsystem';
EWREST_type_2='helpdesk_case';
EWREST_id_2='146';
EWREST_login_3='internal';
EWREST_type_3='helpdesk_case';
EWREST_id_3='145';
```

#### Example 2

Assume an instance of Agiloft is available on localhost, port 8080 and Demo KB. Now we want to retrieve particular fields. 

The following request is issued: 

```javascript
https://localhost:8080/ewws/EWSearch?$KB=Demo&$login=admin&$password=qwerty&$table=helpdesk_case&$lang=en&search=C%3A%20Status%20is%20Closed&query=priority%3DHigh&field=summary&field=priority 

```

If there are no records found, the following result will be returned: 

```javascript
EWREST_id_length = '0';
```

The following result will be returned in the case of four records being found: 

```javascript
EWREST_length = '4';
EWREST_summary_0='Here is a new service request with some tasks';
EWREST_priority_0='High';
EWREST_summary_1='New Employee Setup for Patricia Smith';
EWREST_priority_1='High';
EWREST_summary_2='Upgrading Our Software';
EWREST_priority_2='High';
EWREST_summary_3='Need New Wireless Card for Laptop';
EWREST_priority_3='High';    
```

#### Example 3

Assume an instance of Agiloft is available on localhost, port 8080 and Demo KB. Now we want to retrieve particular fields in addition to the default ones as per the last example.   
We are retrieving data in pages 2 records at a time and are interested in the 2nd page only. Page numbers counts from 0.

The following request is issued: 

```javascript
https://localhost:8080/ewws/EWSearch?$KB=Demo&$login=admin&$password=qwerty&$table=helpdesk_case&$lang=en&search=C%3A%20Status%20is%20Closed&query=priority%3DHigh&field=summary&field=priority&page=1&limit=2
```

If there are no records found, the following result will be returned: 

```javascript
EWREST_id_length = '0';
```

The following result is returned in the case of four records found in total, showing last two ones: 

```javascript
EWREST_length = '2';
EWREST_summary_0='Upgrading Our Software';
EWREST_priority_0='High';
EWREST_summary_1='Need New Wireless Card for Laptop';
EWREST_priority_1='High';
```

#### JavaScript Example

Here is an example for a JavaScript-based client that invokes the REST interface via AJAX: 

```javascript
    function xmlhttpGet (strURL) {
        var xmlHttpReq=false;
        var self=this;
        // Mozilla/Safari
        if (window.XMLHttpRequest) {
            try {
                netscape.security.PrivilegeManager.
enablePrivilege("UniversalBrowserRead");
            } catch (e) {
                alert("Permission UniversalBrowserRead denied.");
            }
            self.xmlHttpReq=new XMLHttpRequest();
        }// IE
        else if (window.ActiveXObject) {
            self.xmlHttpReq=new ActiveXObject("Microsoft.xmlHTTP");
        }
        self.xmlHttpReq.open('GET', strURL, true);
        self.xmlHttpReq.onreadystatechange=requestComplete;
        self.xmlHttpReq.send(null);
    }
    function requestComplete() {
        if (xmlHttpReq.readyState==4||xmlHttpReq.readyState=="complete") {
            eval (self.xmlHttpReq.responseText);
            alert ("Id of new ticket"+EWREST_id);
        }
    }
    function main() {
        xmlhttpGet(' https://localhost:8080/ewws/EWSearch?$KB=Demo&$login=admin&$password=qwerty&$table=helpdesk_case&$lang=en&search=C%3A%20Status%20is%20Closed&query=priority%3DHigh&field=summary&field=priority');
    } 
```

## Pagination

Page numbers start with 0 (zero). A page size limit value of zero indicates "all records" and so all records are returned on page 0 when limit 0 is specified; otherwise with a non-zero page number an empty result is returned, meaning no records. When a page is not found, an empty result is returned.

A call using pagination always returns a page worth of data. However, to truly take advantage of pagination, all other parameters must remain the same. If the table, fields, saved search, query, or limit on a subsequent call is different from the previous one, the underlying query is automatically rebuilt and re-run. As such only one "open" query is allowed per client session. If the client requires multiple queries to be iterated in parallel, the client code should create multiple sessions using the same login credentials.

This method doesn't support multi-threading; the client is responsible for restricting access to a single thread, such that one client thread = one session = one open query.

The query will remain "open" until the session is closed, either by an explicit logout by the client or by an automatic session timeout. If the application server discards the underlying low-level objects as a result of resource management, the query will be rebuilt and re-run automatically on the next call.

If the query is rebuilt and re-run, the result of the next call may not be fully consistent with the results of the previous call, as the underlying data may have changed; for example, a record  might have been deleted, or the sort order for the search might have been changed. As a result, the dataset might appear to have gaps, or the logical page boundaries might shift when iterating the query page by page.

The REST interface creates a new session and performs an explicit logout for each call. As such, though pagination is available, the query will always be rebuilt and rerun. The ability to issue multiple REST calls within a single session, similar to the SOAP interface, is in development.

# Error Codes

The below error codes are for EWSearch only, but are not an extensive list of possible error codes. For any errors not listed here, consult the General Error Codes section of [https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715778](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715778).

|  |  |  |  |
| --- | --- | --- | --- |
| **Scenario ** | **Type** | **Code** | **Description** |
| When the search parameter is search and the savedSearch is NULL for the provided search value | VALIDATION | 400 | EWWrongDataException   → No search <savedSearch> for table <tableName> |
| When the provided fieldName in the request doesn’t exist | VALIDATION | 400 | EWWrongDataException   → No column <columnName> in table <tableName> |
| When there are issues creating or using the   data retriever object | SERVER | 500 | EWUnexpectedException   → error creating data retriever |
| EWUnexpectedException → error   using retriever |
| Exception → Error while   processing data conversion |
| When there are issues retrieving records | SERVER | 500 | EWUnexpectedException   → error retrieving records |

> Macro (hide-if)
> 
> #### Related articles
> 
> > Macro (contentbylabel)