> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.awork.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server. # Filtering > Learn how to filter the awork API responses. The Awork API supports a wide range of filters that can be applied to most of our API endpoints. A filter can be applied by adding a `filterby` expression to the request URL: ```sh /users?filterby=firstName eq 'Sebastian' ``` Important: Special characters (like `?`, `&` and `=`) within a string filter value need to be properly URL encoded. Correct: ```sh /companies?filterby=name eq 'awork %26 co' ``` Incorrect: ```sh /companies?filterby=name eq 'awork & co' ``` Use two single quotes to escape an apostrophe inside a string literal: ```sh /me/allavailabletasks?filterby=name eq 'user''s task' ``` If you want to filter by a nested property, you can do this by separating the properties by `/`, for example: ```sh /projects?filterby=company/name eq 'awork' ``` ## Logical Operations You can invert the expression by using `not` before the statement ```sh /users?filterby=not firstName eq 'Sebastian' ``` Furthermore, you can combine expressions using the logical operator `and` ```sh /projects?filterby=plannedDuration le 200 and plannedDuration gt 3.5 ``` as well as the logical operator `or` ```sh /projects?filterby=plannedDuration le 200 or plannedDuration gt 300 ``` Precedence is defined with `(` and `)`. You can also use the `any` operator in combination with `eq false` to filter for items that do not contain a specific value. ```sh /me/allavailabletasks?filterby=lists/any(l: l/name eq 'Draft') eq false ``` ## Combining Filtering and Ordering You can combine filtering and ordering by adding the `orderby` parameter to the URL. ```sh /projects?filterby=duration le 6000 and duration gt 1000&orderby=duration desc ``` ## Data Types The data types DateTime and Guid have to be prefixed with the corresponding type identifier `datetime` and `guid`, respectively, e.g. **`Filter by DateTime`** ```sh title="Filter by DateTime" /users?filterby=birthDate ge datetime'2018-04-03T00:00' ``` **`Filter by Guid`** ```sh title="Filter by Guid" /users?filterby=id eq guid'12345678-aaaa-bbbb-cccc-ddddeeeeffff' ``` | Type | Example | | ------------ | ------------------------------------------ | | **Null** | null | | **Boolean** | true \| false | | **Byte** | 0x22 | | **DateTime** | datetime'2000-12-12T12:00' | | **Decimal** | 2.345M | | **Double** | 2.029 | | **Single** | 2.0f | | **Guid** | guid'12345678-aaaa-bbbb-cccc-ddddeeeeffff' | | **Int** | 32 | | **Long** | 64L | | **String** | 'Hello awork' | ## Operators | Operator | Description | Query | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `eq` | The `eq` operator filters and returns the items which match the filter term. | `/users?filterby=firstName eq 'Neil'` | | `ne` | The `ne` operator filters and returns the items which do not match the filter term. | `/users?filterby=firstName ne 'Neil'` | | `endswith` | The `endswith` operator filters and returns the items which end with the filter term. | `/users?filterby=endswith(firstName,'Neil')` | | `startswith` | The `startswith` operator filters and returns the items which start with the string. | `/users?filterby=startswith(firstName,'Neil')` | | `substringof` | The `substringof` operator filters and returns the items which contain the filter term. | `/users?filterby=substringof('Neil',firstName)` | | `gt` | The `gt` operator filters and returns the items which are greater than the filter term. | `/users?filterby=birthDate gt datetime'2018-04-03T00:00'` | | `lt` | The `lt` operator filters and returns the items which are less than the filter term. | `/users?filterby=birthDate lt datetime'2018-04-03T00:00'` | | `le` | The `le` operator filters and returns the items which are less than or equal to the filter term. | `/users?filterby=birthDate le datetime'2018-04-03T00:00'` | | `ge` | The `ge` operator filters and returns the items which are greater than or equal to the filter term. | `/users?filterby=birthDate ge datetime'2018-04-03T00:00'` | | `in` | The `in` operator filters and returns the items where the property value matches any value in the provided list. | `/tasks?filterby=tags/any(t: t/name in ('Draft','In Progress'))` | | `any` | The `any` operator iterates through the main entity (Project), executes the condition and returns the filtered list of projects where any member with a first name of 'Neil' exists. | `/projects?filterby=members/any(p: p/firstName eq 'Neil')` | | `count` | The `count` operator iterates through the main entity (Project), and returns the filtered list of projects that have less than 10 members. Also supports conditional counting with expressions. | `/projects?filterby=members/count() lt 10` or `/projects?filterby=members/count(m: m/firstName eq 'Neil') gt 0` | | `tolower` | The `tolower` operator can be used to convert strings to lowercase, which can be helpful for string comparison. | `/projects?filterby=tolower(name) eq 'website'` | > **Warning** > > Not all operators can be used in combination or nested. ### Special Operator for the Current User | Expression | Description | Example | | ---------- | ---------------------------- | ----------------------------- | | `me.id` | Filters for the current user | `/users?filterby=id eq me.id` | ### Special Operators for Date and Time | Expression | Description | Example | | ----------- | ----------------------------------------- | ------------------------------------ | | `now` | Filters for less than current date-time | `/tasks?filterby=dueOn lt now` | | `sow` | Filters for greater than start of week | `/tasks?filterby=dueOn gt sow` | | `eow` | Filters for greater than end of week | `/tasks?filterby=dueOn gt eow` | | `som` | Filters for greater than start of month | `/tasks?filterby=dueOn gt som` | | `eom` | Filters for greater than end of month | `/tasks?filterby=dueOn lt eom` | | `today` | Filters for today | `/tasks?filterby=dueOn eq today` | | `today-30d` | Filters for a relative date in the past | `/tasks?filterby=dueOn gt today-30d` | | `today+5d` | Filters for a relative date in the future | `/tasks?filterby=dueOn gt today+5d` |