---
title: Search Records
slug: search-records
docTags: 
createdAt: 2025-08-11T11:13:48.000Z
---

## Overview

The Search Records action enables you to programmatically query records from Swimlane applications within playbooks. You can search using complex filter conditions, control the order in which records are returned, limit results, paginate through large result sets, and specify which fields to return. The action uses the same filter builder functionality as [building filters in records](#).

## Key Benefits

- **Native Action:** Integrated directly into the playbook builder for streamlined workflow creation.
- **Flexible Filtering:** Build complex search queries using multiple conditions and operators.
- **Explicit Ordering:** Sort records by Tracking ID in ascending or descending order to retrieve the oldest or newest matching records.
- **Field Selection:** Return entire records or only specific fields to optimize data transfer.
- **Pagination Support:** Use **Max Records** and **Page Number** to retrieve specific portions of an ordered result set.
- **At Least Once Execution:** Ensures search results are retrieved even if the playbook is retried.

## Inputs

The Search Records action requires the following inputs:

### Required Inputs

- **Application:** Select an application by either:
  - **Application ID**: The unique identifier of the application
  - **Application Name**: The name of the application
  - Provide either `applicationId` or `applicationName`, but not necessarily both.
- **Filters:** Filter conditions to apply to the search. Can be:
  - **Empty/No filters**: Returns all records in the application (up to the limit)
  - **Simple filters**: Array of filter conditions
  - **Complex filters**: Nested clauses with AND/OR logic
- **Filter Type:** How multiple filter conditions are combined:
  - **AND** (default): All conditions must be true
  - **OR**: At least one condition must be true

### Optional Inputs

- **Order:** Configure how matching records are sorted before the record limit and pagination settings are applied.
  - **Sort by Field:** Records are currently sorted using the numeric portion of the Tracking ID. Only Tracking ID is supported.
  - **Sort Direction:**
    - **Ascending:** Returns records from oldest to newest.
    - **Descending:** Returns records from newest to oldest.
  - Sorting by Tracking ID closely follows the record creation order.
  - For high-volume applications or correlation-heavy playbooks, prefer Tracking ID sort with pagination (**Page Number** and **Max Records**) instead of requesting very large result sets in a single run.
  - Sorting by other fields, including Last Updated, is not currently supported.
- **Return Fields:** Specify which fields to return in the results:
  - **All fields** (default): Returns complete record data
  - **Specific fields**: Returns only the selected field keys
  - If `returnFields` is empty or not specified, all fields are returned.
- **Max Records:** Maximum number of records to return per page:
  - **Default**: 1000 records (if Max Records is 0 or not specified)
  - **Maximum**: 1000 records
  - **Minimum**: 1 record
  - The limit is clamped between 1 and 1000. If you need more records, use pagination with Page Number.
- **Page Number:** Specify which page of the ordered result set to return.
  - **Default**: `1`
  - Page Number works with Max Records to divide matching records into pages.
  - Use a positive whole number.
  - **Important:** Do not enter a negative Page Number.
  - **Example:** Sort Direction Descending, Page Number `3`, Max Records `50` returns records 101–150 of the ordered result set.
- **Date Filter Type:** Optional date filter type for date field filters (minute, hour, day, week, month, quarter, year, allTime).

## Filter Operators

The Search Records action supports the following filter operators:

- **equals**: Field value exactly matches the specified value
- **doesNotEqual**: Field value does not match the specified value
- **contains**: Field value contains the specified value (for strings)
- **containsAny**: Field value contains any of the specified values
- **excludes**: Field value does not contain the specified value
- **lessThan**: Field value is less than the specified value
- **lessThanOrEqual**: Field value is less than or equal to the specified value
- **greaterThan**: Field value is greater than the specified value
- **greaterThanOrEqual**: Field value is greater than or equal to the specified value
- **exists**: Field exists (has a value)
- **previous**: For date fields, matches previous period
- **current**: For date fields, matches current period
- **next**: For date fields, matches next period
- **hour**: For date fields, matches specific hour
- **dayOfWeek**: For date fields, matches specific day of week

**Note:** Available operators may vary depending on the field type, such as text, number, or date.

## Configuring the Search Records Action

### Step 1: Select Application

1. From the **Inputs** tab, select an application:
   - Choose from the dropdown list of available applications, or
   - Use an expression to reference an application ID or name dynamically

### Step 2: Configure Filter Conditions

1. Click **Add Condition** or use the condition builder to create filter conditions.
2. For each condition:
   - **Field**: Click **Field** to choose the field you want to filter on. Only fields available in the selected application are shown.
   - **Operator**: Choose how the filter is evaluated using the Operator dropdown. Available operators depend on the field type:
     - **Text fields**: equals, doesNotEqual, contains, containsAny, excludes, exists
     - **Number fields**: equals, doesNotEqual, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, exists
     - **Date fields**: equals, doesNotEqual, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, previous, current, next, hour, dayOfWeek, exists
   - **Value**: Enter or select the value to compare against the chosen field and operator. You can use:
     - Static values
     - Playbook properties from upstream actions
     - Playbook inputs
     - Expressions
3. **Add Multiple Conditions**: Add additional conditions to refine your filter.
4. **Filter Type**: Use the ALL/ANY (AND/OR) selector at the top:
   - **ALL (AND)**: All conditions must be true for a record to be included (default).
   - **ANY (OR)**: At least one condition must be true for inclusion.

**Note:** If you do not add any filter conditions, all records in the application will be returned (up to the limit).

### Step 3: Configure Return Fields

Choose what data to return:

- **Find entire records**: Returns all fields of the matching records (default behavior if no fields are specified).
- **Return specific fields**: Select specific fields to return only those field values, reducing data transfer and improving performance.

**Example:** If you only need the tracking ID and status, select only those fields instead of returning all record data.

### Step 4: Configure Record Order

In the **Order** section, configure how records are returned:

1. In **Sort by Field**, select **Tracking ID**.
2. Select a **Sort Direction**:
   - **Ascending** returns records from oldest to newest.
   - **Descending** returns records from newest to oldest.

The action sorts records using the numeric portion of the Tracking ID. This prevents values from being sorted as text and keeps the result order aligned with record creation time.

**Note:** New Search Records actions use **Descending** as the default sort direction. Existing actions retain their current behavior unless you update their ordering configuration.

### Step 5: Configure Pagination

Configure the following options:

### Max Records

Enter the maximum number of records to return per page.

- **Default**: `1000`
- **Maximum**: `1000`
- **Minimum**: `1`

Max Records is applied after the records are filtered and sorted.

### Page Number

Enter the page of records to return.

- **Default**: `1`
- Use a positive whole number.
- Page Number works with Max Records to determine the portion of the result set to retrieve.

### Example: Retrieve the Latest 100 Records

Configure the action as follows:

- **Sort by Field**: Tracking ID
- **Sort Direction**: Descending
- **Page Number**: `1`
- **Max Records**: `100`

### Example: Retrieve the Next 100 Records

Configure the action as follows:

- **Sort by Field**: Tracking ID
- **Sort Direction**: Descending
- **Page Number**: `2`
- **Max Records**: `100`

### Step 6: Apply Changes

Click **Apply** to save your configuration.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/zsjeyCyR2Wsqy1cITTWvT_cavnas-search-record.png" size="56" width="1055" height="923" darkWidth="1055" darkHeight="923" position="center" alt="Search Records Configuration" showCaption="false"}

## Outputs

The Search Records action provides the following outputs:

### Success Output

When the search completes successfully, the action returns:

- Records in `result.records` are returned in the configured Tracking ID order before the configured pagination and record limit are applied.
- `result.records`: An array of matching records. Each record is an object containing field key/value pairs.
  - If `returnFields` was specified, only those fields are included.
  - If `returnFields` was empty or not specified, all fields are included.
  - Each record includes a `tracking-id` field.
- `result.count`: The total number of matching records (may be limited by `isCountLimited`).
- `result.limit`: The limit that was applied to this search result.
- `result.pageNumber`: The page number that was requested.
- `result.hasNextPage`: A boolean indicating whether there are more pages of results available.
- `result.isCountLimited`: A boolean indicating whether the total count was limited for performance purposes.

**Example:** Access search results in downstream actions:

### Error Output

If the search fails, the action returns:

- `error`: Error information containing details about why the search failed.

**Common Error Scenarios:**

- Application not found
- Invalid filter syntax
- Invalid field references
- Permission errors
- Invalid limit or page number values

## Use Cases

### Example 1: Retrieve the Most Recent Records

**Scenario:** Retrieve the 100 most recently created records from an application.

Configure the action as follows:

1. Select the required application.
2. Add any required filter conditions.
3. Set **Sort by Field** to **Tracking ID**.
4. Set **Sort Direction** to **Descending**.
5. Set **Page Number** to `1`.
6. Set **Max Records** to `100`.
7. Select the required return fields.
8. Click **Apply**.

### Example 2: Search by Tracking ID

**Scenario:** Retrieve a specific record by its Tracking ID.

**Endpoint:**

`https://de1.swimlane.app:443/api/account/{account_id}/tenant/{tenant_id}/app/{app_id}/record/tracking/{tracking_id}`

**Required Parameters:**

- **account\_id**: The unique identifier for the Swimlane account.
- **tenant\_id**: The tenant associated with the account, representing the isolated environment within Swimlane.
- **app\_id**: The application identifier where the record exists.
- **tracking\_id**: The unique tracking ID of the record to retrieve.

**Example Usage:**

**Response Example:**

**Screenshot:**

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/lXnXEXy3-NrSjfKWSywb2_image-20230921-194813.png" size="62" width="3352" height="3162" darkWidth="3352" darkHeight="3162" position="center" alt="Search Record Action" showCaption="false"}

This screenshot shows the **Search Record** setup in Swimlane, where you define the application name, filters (including the Tracking ID), and the fields to return.

### SEARCH (With HTTP Action)

The SEARCH (With HTTP Action) method allows users to perform a search directly through the Swimlane API using an HTTP GET request. This approach can be used to retrieve records based on specific criteria by providing the tracking ID and other filter parameters.

**HTTP GET Endpoint:**

`https://de1.swimlane.app:443/api/account/{account_id}/tenant/{tenant_id}/app/{app_id}/record/tracking/{tracking_id}`

**Authentication:** An API key or bearer token is required to authenticate the request. Include it in the request header as shown below:

**Request Example:**

**Response Example:**

**Screenshot:**

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/OZfDHEuBj4tfXtao7GtOr_image-20230921-195823.png" size="92" width="3110" height="1122" position="center" alt="HTTP Action Get Record" darkWidth="3110" darkHeight="1122" showCaption="false"}

This screenshot illustrates the configuration of the HTTP Action for **Get Record** in Swimlane, using a direct HTTP request to search by Tracking ID.

## Best Practices

- **Use Specific Return Fields:** When you only need certain fields, specify them in `returnFields` to reduce data transfer and improve performance.
- **Set Appropriate Limits:** Use Max Records to prevent retrieving too many records at once. The default limit is 1000 records.
- **Use Pagination for Large Result Sets:** If you need more than 1000 records, use **Page Number** with **Max Records** to retrieve additional pages.
- **Set the Sort Direction Explicitly:** Select Ascending or Descending whenever the record order affects downstream processing.
- **Use Descending for Recent Records:** Use Descending order with a low Max Records value to retrieve the latest matching records without over-fetching.
- **Use Ascending for Historical Processing:** Use Ascending order when records must be processed from oldest to newest.
- **Combine Sorting and Pagination Carefully:** Apply sorting before using Max Records or Page Number so that each request retrieves a stable portion of the result set.
- **Avoid Post-Processing Where Possible:** Use the action's ordering controls instead of retrieving additional records and sorting them later in Transform Data or scripts.
- **Tracking ID Sorting:** Sorting is performed using the numeric portion of the Tracking ID rather than as a text value.
- **Optimize Filter Conditions:**
  - Use specific filters to narrow results before processing.
  - Place the most selective filters first.
  - Use `exists` operator to check for non-null values.
- **Handle Empty Results:** Always check if `result.records` is empty before processing.
- **Use Tracking IDs from Results:** Store or use tracking IDs from search results for downstream operations like updating or deleting records.
- **Check hasNextPage:** When using pagination, always check `hasNextPage` to determine if more results are available.
- **Consider Performance:**
  - Avoid searching without filters on large applications.
  - Use returnFields to limit data transfer.
  - Use appropriate limits to balance between completeness and performance.

## Troubleshooting

- **No Records Returned:**
  - Verify filter conditions are correct.
  - Check that field values match exactly (case-sensitive for text fields).
  - Ensure the application contains records matching your criteria.
  - Review the `count` value to see total matches.
- **Too Many Records:**
  - Add more specific filter conditions.
  - Reduce the Max Records value.
  - Use returnFields to reduce data size.
- **Missing Fields in Results:**
  - If you specified `returnFields`, ensure the field keys are correct.
  - Check that fields exist in the application.
  - Verify field keys match the application's field definitions.
- **Records Are Returned in an Unexpected Order:**
  - Verify that **Sort by Field** is set to **Tracking ID**.
  - Verify that the required sort direction is selected.
  - Use **Descending** for newest-to-oldest results.
  - Use **Ascending** for oldest-to-newest results.
  - Confirm that an existing action has been explicitly updated, because existing actions retain their previous behavior.
- **Records Are Missing or Repeated Across Requests:**
  - Verify the Max Records and Page Number values.
  - Ensure the same filters and sort direction are used for each request.
  - Do not change the sort direction between pagination requests.
  - Avoid using negative Page Number values.
  - Increment **Page Number** by 1 for each subsequent request while keeping Max Records constant.
- **Sorting Takes Longer Than Expected:**
  - Add filter conditions to reduce the number of matching records.
  - Use an appropriate Max Records value.
  - Avoid querying all records in very large applications unless required.
  - Sorting is currently limited to Tracking ID to reduce performance impact.
- **Pagination Not Working:**
  - Ensure **Page Number** uses a positive whole number (default is 1).
  - Check that **Max Records** is set appropriately.
  - Verify `hasNextPage` to determine if more pages exist.
  - Use **Page Number** with **Max Records** only.
- **Application Not Found:**
  - Verify the application ID or name is correct.
  - Ensure the application exists and is accessible.
  - Check that application references are properly formatted.
- **Filter Errors:**
  - Verify filter syntax is correct.
  - Ensure field IDs/keys match application field definitions.
  - Check that operator is appropriate for the field type.
  - Validate that filter values match the expected data types.
- **Performance Issues:**
  - Add more specific filters to narrow results.
  - Use `returnFields` to limit data transfer.
  - Consider using smaller Max Records values and pagination.
  - Avoid searching without filters on very large applications.