---
title: Filter Operators
description: Complete reference for all filter operators available in the TraceRTM API
---

# Filter Operators

This reference documents all filter operators available in the TraceRTM API, including their syntax, supported field types, and usage examples.

## Operator Quick Reference

| Operator | Description | Field Types | Example |
|----------|-------------|-------------|---------|
| `eq` | Equals | All | `status[eq]=approved` |
| `ne` | Not equals | All | `status[ne]=deprecated` |
| `gt` | Greater than | Number, Date | `created_at[gt]=2024-01-01` |
| `gte` | Greater or equal | Number, Date | `score[gte]=80` |
| `lt` | Less than | Number, Date | `due_date[lt]=2024-12-31` |
| `lte` | Less or equal | Number, Date | `priority_score[lte]=5` |
| `in` | Value in list | String, Number | `status[in]=draft,review` |
| `nin` | Value not in list | String, Number | `type[nin]=bug,task` |
| `contains` | Contains substring | String | `title[contains]=auth` |
| `startswith` | Starts with | String | `key[startswith]=REQ-` |
| `endswith` | Ends with | String | `name[endswith]-v2` |
| `regex` | Regex match | String | `key[regex]=^REQ-[0-9]+$` |
| `all` | Array has all | Array | `tags[all]=mvp,security` |
| `any` | Array has any | Array | `tags[any]=urgent,block` |
| `exists` | Field exists | Any | `assignee[exists]=true` |
| `null` | Field is null | Any | `due_date[null]=true` |
| `empty` | Field is empty | String, Array | `tags[empty]=false` |
| `between` | Between range | Number, Date | `score[between]=50,100` |
| `size` | Array size | Array | `tags[size]=3` |

---

## Comparison Operators

### eq (Equals)

Returns items where the field exactly matches the value.

**Syntax:** `field[eq]=value` or `field=value`

**Supported Types:** String, Number, Boolean, Date

```bash
# Explicit eq operator
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?status[eq]=approved"

# Implicit eq (same result)
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?status=approved"

# Boolean field
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.is_critical[eq]=true"
```

### ne (Not Equals)

Returns items where the field does not match the value.

**Syntax:** `field[ne]=value`

**Supported Types:** String, Number, Boolean, Date

```bash
# Items NOT in deprecated status
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?status[ne]=deprecated"

# Items NOT assigned to specific user
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?assignee[ne]=user_abc123"

# Items NOT of type 'task'
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?type[ne]=task"
```

### gt (Greater Than)

Returns items where the field is greater than the value.

**Syntax:** `field[gt]=value`

**Supported Types:** Number, Date

```bash
# Items created after specific date
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?created_at[gt]=2024-01-15T00:00:00Z"

# Items with priority score greater than 5
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.priority_score[gt]=5"

# Items with more than 8 story points
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.story_points[gt]=8"
```

### gte (Greater Than or Equal)

Returns items where the field is greater than or equal to the value.

**Syntax:** `field[gte]=value`

**Supported Types:** Number, Date

```bash
# Items updated on or after date
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?updated_at[gte]=2024-01-01T00:00:00Z"

# Items with at least 3 story points
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.story_points[gte]=3"
```

### lt (Less Than)

Returns items where the field is less than the value.

**Syntax:** `field[lt]=value`

**Supported Types:** Number, Date

```bash
# Items created before specific date
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?created_at[lt]=2024-01-01T00:00:00Z"

# Items with due date before end of month
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?due_date[lt]=2024-01-31T23:59:59Z"
```

### lte (Less Than or Equal)

Returns items where the field is less than or equal to the value.

**Syntax:** `field[lte]=value`

**Supported Types:** Number, Date

```bash
# Items with at most 5 story points
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.story_points[lte]=5"

# Items due on or before deadline
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?due_date[lte]=2024-02-28T23:59:59Z"
```

### between (Range)

Returns items where the field is within a range (inclusive).

**Syntax:** `field[between]=min,max`

**Supported Types:** Number, Date

```bash
# Items with story points between 3 and 8
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.story_points[between]=3,8"

# Items created in January 2024
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?created_at[between]=2024-01-01T00:00:00Z,2024-01-31T23:59:59Z"

# Items with priority score 5-10
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.priority_score[between]=5,10"
```

---

## Collection Operators

### in (Value In List)

Returns items where the field matches any value in the list.

**Syntax:** `field[in]=value1,value2,value3`

**Supported Types:** String, Number

```bash
# Items with any of these statuses
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?status[in]=draft,in_review,approved"

# Items of specific types
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?type[in]=requirement,user_story,task"

# Items assigned to any of these users
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?assignee[in]=user_abc,user_def,user_ghi"
```

### nin (Value Not In List)

Returns items where the field does not match any value in the list.

**Syntax:** `field[nin]=value1,value2,value3`

**Supported Types:** String, Number

```bash
# Items NOT in these statuses
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?status[nin]=deprecated,rejected,archived"

# Exclude specific item types
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?type[nin]=bug,defect"
```

---

## Array Operators

### all (Array Contains All)

Returns items where the array field contains ALL specified values.

**Syntax:** `field[all]=value1,value2`

**Supported Types:** Array

```bash
# Items tagged with BOTH mvp AND security
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?tags[all]=mvp,security"

# Items in all specified categories
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.categories[all]=frontend,performance"
```

### any (Array Contains Any)

Returns items where the array field contains ANY of the specified values.

**Syntax:** `field[any]=value1,value2`

**Supported Types:** Array

```bash
# Items tagged with EITHER urgent OR blocking
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?tags[any]=urgent,blocking"

# Items in any specified component
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.components[any]=auth,payments,notifications"
```

### size (Array Size)

Returns items where the array has a specific number of elements.

**Syntax:** `field[size]=number` or `field[size][operator]=number`

**Supported Types:** Array

```bash
# Items with exactly 3 tags
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?tags[size]=3"

# Items with more than 5 tags
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?tags[size][gt]=5"

# Items with 1-3 attachments
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?attachments[size][gte]=1&attachments[size][lte]=3"
```

---

## Text Operators

### contains (Contains Substring)

Returns items where the field contains the substring (case-insensitive).

**Syntax:** `field[contains]=substring`

**Supported Types:** String

```bash
# Items with "authentication" in title
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?title[contains]=authentication"

# Items with "API" in description
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?description[contains]=API"

# Case insensitive - matches "Auth", "auth", "AUTH"
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?title[contains]=auth"
```

### startswith (Starts With)

Returns items where the field starts with the specified prefix.

**Syntax:** `field[startswith]=prefix`

**Supported Types:** String

```bash
# Items with keys starting with "REQ-"
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?key[startswith]=REQ-"

# Items in security module
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.module[startswith]=security/"
```

### endswith (Ends With)

Returns items where the field ends with the specified suffix.

**Syntax:** `field[endswith]=suffix`

**Supported Types:** String

```bash
# Items ending with "-v2"
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?title[endswith]=-v2"

# Items with specific file extension
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.filename[endswith]=.ts"
```

### regex (Regular Expression)

Returns items where the field matches the regex pattern.

**Syntax:** `field[regex]=pattern`

**Supported Types:** String

```bash
# Items with keys matching pattern REQ-001 through REQ-999
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?key[regex]=^REQ-[0-9]{3}$"

# Items with semantic version in title
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?title[regex]=v[0-9]+\.[0-9]+\.[0-9]+"

# Items with email addresses in description
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?description[regex]=[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"
```

**Regex Flags:**

```bash
# Case-insensitive regex (prefix with (?i))
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?title[regex]=(?i)auth.*login"
```

---

## Existence Operators

### exists (Field Exists)

Returns items where the field exists (is defined, even if null or empty).

**Syntax:** `field[exists]=true` or `field[exists]=false`

**Supported Types:** Any

```bash
# Items with an assignee field (even if null)
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?assignee[exists]=true"

# Items without a due_date field
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?due_date[exists]=false"

# Items with custom field defined
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.risk_level[exists]=true"
```

### null (Field Is Null)

Returns items where the field is null.

**Syntax:** `field[null]=true` or `field[null]=false`

**Supported Types:** Any

```bash
# Items without an assignee (null)
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?assignee[null]=true"

# Items with a due date set (not null)
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?due_date[null]=false"
```

### empty (Field Is Empty)

Returns items where the field is empty (empty string or empty array).

**Syntax:** `field[empty]=true` or `field[empty]=false`

**Supported Types:** String, Array

```bash
# Items with no tags
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?tags[empty]=true"

# Items with non-empty description
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?description[empty]=false"

# Items without attachments
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?attachments[empty]=true"
```

---

## Date/Time Operators

### Date Formats

TraceRTM accepts multiple date formats:

| Format | Example |
|--------|---------|
| ISO 8601 | `2024-01-20T10:30:00Z` |
| ISO 8601 with offset | `2024-01-20T10:30:00+05:30` |
| Date only | `2024-01-20` (treats as start of day UTC) |
| Relative | `now-7d`, `now-1h`, `today`, `yesterday` |

### Relative Date Syntax

| Expression | Description |
|------------|-------------|
| `now` | Current timestamp |
| `today` | Start of today (00:00:00 UTC) |
| `yesterday` | Start of yesterday |
| `now-1h` | 1 hour ago |
| `now-7d` | 7 days ago |
| `now-1w` | 1 week ago |
| `now-1M` | 1 month ago |
| `now+7d` | 7 days from now |

### Examples

```bash
# Items created in the last 7 days
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?created_at[gte]=now-7d"

# Items updated today
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?updated_at[gte]=today"

# Items due in the next 2 weeks
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?due_date[lte]=now+14d&due_date[gte]=now"

# Items created last month
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?created_at[gte]=now-1M&created_at[lt]=today"

# Items not updated in 30 days (stale)
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?updated_at[lt]=now-30d"
```

---

## Operator Combinations

### Combining Multiple Operators

You can combine multiple operators on the same or different fields:

```bash
# Range: items with score between 50 and 100
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?custom.score[gte]=50&custom.score[lte]=100"

# Multiple fields: approved requirements created this month
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?type=requirement&status=approved&created_at[gte]=now-1M"

# Complex: high priority items NOT in done status, with tags
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?priority[in]=high,critical&status[nin]=done,archived&tags[any]=mvp,urgent"
```

### Operator Precedence

When multiple operators are combined:
1. All conditions are ANDed together by default
2. `[in]` and `[any]` provide OR logic within a field
3. Use filter expressions for complex OR logic across fields

---

## Error Handling

### Invalid Operator

```json
{
  "error": {
    "code": "INVALID_FILTER_OPERATOR",
    "message": "Unknown operator 'invalid' for field 'status'",
    "details": {
      "field": "status",
      "operator": "invalid",
      "valid_operators": ["eq", "ne", "in", "nin"]
    }
  }
}
```

### Type Mismatch

```json
{
  "error": {
    "code": "FILTER_TYPE_MISMATCH",
    "message": "Operator 'gt' not supported for string field 'title'",
    "details": {
      "field": "title",
      "field_type": "string",
      "operator": "gt",
      "supported_operators": ["eq", "ne", "in", "nin", "contains", "startswith", "endswith", "regex"]
    }
  }
}
```

### Invalid Regex

```json
{
  "error": {
    "code": "INVALID_REGEX",
    "message": "Invalid regular expression pattern",
    "details": {
      "field": "key",
      "pattern": "[invalid",
      "error": "missing closing bracket"
    }
  }
}
```

---

## Related Documentation

- [Filtering](/docs/api-reference/rest-api/filtering) - Filtering overview
- [Sorting](/docs/api-reference/rest-api/sorting) - Sort filtered results
- [Search](/docs/api-reference/rest-api/search) - Full-text search
