---
title: REST API - Filter Parameter
slug: rm/rest-api-filter-parameter
docTags: 
createdAt: 2026-06-09T13:38:46.103Z
---

The filter parameter allows you to narrow the results that are included in the response to your request. If no filter parameters are specified, all artifacts are returned. If a filter parameter is specified, artifacts are only returned if the artifact matches the specified criteria. The filter parameters can be used individually, or combined to narrow results further.

# Syntax

The filter parameter must be specified using the following syntax:

```perl
filter={artifact-id eq (‘1’ or ‘2’ or ‘3’);artifact-type eq (‘Actor’);artifact-HasComments eq ‘true’;property-'My prop' eq 1;property-my2prop eq (‘my name’ or ‘your name’)}
```

# Method

The filter parameter must be submitted using the [REST API - HTTP POST Method](docId\:Hsi_LzXS8g_RX_ydUdZKg).

To submit information using the HTTP POST method, you must add the following information to the request header to override the GET method.

```sql
X-HTTP-Method-Override: GET
```

Then, include your filter parameter in the request body.  For example:

```perl
filter={artifact-type eq (‘UI Mockup');
```

# Parameters

- `Artifact-Id`: If specified, artifacts are only returned if the ID of the artifact matches one of the given IDs.
- `Artifact-Type`: If specified, artifacts are only returned if the artifact type matches one of the given artifact types.
- `Artifact-HasAttachments`: If set to true, artifacts are only returned if there is at least one associated attachment. If set to false, artifacts are only returned if there are no associated attachments.
- `Artifact-HasComments`: If set to true, artifacts are only returned if there is at least one associated comment. If set to false, artifacts are only returned if there are no associated comments.
- `Property-[Name]`: If specified, artifacts are only returned if the artifact's property value matches the given value.

# Supported Operators

The supported operators varies depending on the data that you want to query.  The table below outlines the supported operators for each type of data.

![](https://files.helpdocs.io/4rdnduk17o/articles/ypblr6vras/1574104796292/supporters-operators.png)

# Tips and Important Notes

- Filtering on users and groups:
  - When filtering on a user, you must use the user id prepended with the letter 'u'. For example, if the user ID was 20, you need to specify 'u20'.
  - When filtering on a group, you must use the group id prepended with the letter 'g'. For example, if the group ID was 18, you need to specify 'g18'.
- Filtering on dates and audit-datetime:
  - Dates are measured using just the date (example: '2013-05-11') while Author History fields ('Created On' and 'Last Edited On') are measured using nano-seconds (example: '2013-01-22T16:08:14.2170000Z'). Because of this difference, if you perform a greater than ('gt') filter, the results will be different. For example, a greater than operation on a date will return artifacts that match the following day. Alternatively, a greater than operation on the 'Created By' field will return artifacts after midnight on the same day.
- Filtering on custom properties:
  - If you are filtering on custom properties, you must include quotations around the property name if it includes a space. For example: property-'Focus Group'.

# Examples

Retrieve all artifacts that have associated comments:

```perl
filter={artifact-HasComments eq (‘true’);}
```

Retrieve all artifacts of type 'Actor':

```perl
filter={artifact-type eq (‘Actor’);}
```

Retrieve all artifacts of either type 'Actor' or 'Use Case':

```ini
filter={artifact-type eq ('Use Case' or 'Actor');}
```

Retrieve all artifacts of type 'Textual Requirement' that have at least one attachment:

```perl
filter={artifact-type eq ('Textual Requirement'); artifact-HasAttachments eq ('true');}
```

Retrieve all artifacts where the Priority property of the artifact is set to 'High':

```perl
filter={property-priority eq ('High');}
```

Retrieve all artifacts where the Focus Group property of the artifact is equal to a group with an ID of 9 or 10:

```perl
filter={property-'Focus Group' eq ('g9' and 'u10')}
```

Retrieve all artifacts that were last edited between midnight on May 11th and midnight on May 14th inclusive:

```ini
filter={property-'Last Edited On' bi ('2013-05-11' and '2013-05-14')}
```

Retrieve all artifacts that were created after midnight on May 14th:

```ini
filter={property-'Created On' gt ('2013-05-14')}
```