> For the complete documentation index, see [llms.txt](https://support.attackforge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api/advanced-query-filter.md).

# ADVANCED QUERY FILTER

## Overview

The Advanced Query Filter lets you choose exactly which records a Self-Service API method returns, such as only Open Critical vulnerabilities, or writeups imported from Nessus. You write the filter in a query language like MongoDB's, and send it as a query parameter.

Filters work only with some API methods. Check each method in the [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started) to see whether it supports one.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FOHAtDZnL5BUphWPG0gyj%2Fadvanced-query-filter-at-a-glance.svg?alt=media&amp;token=f07ed9bf-2d15-483b-b0c2-bc9a6f88e543" alt=""><figcaption></figcaption></figure>

## Why it matters

| Benefit                         | What it means                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| **Get only what you need**      | Filter on the server, so less data comes back and requests are faster                       |
| **Precise questions**           | Combine conditions with AND and OR, and match text with regular expressions                 |
| **Relative dates**              | Ask for "the last 7 days" or "due in the next week" without working out dates               |
| **Custom fields and tags**      | Filter on your own custom fields and tags, not just built-in fields                         |
| **One language in many places** | Use the same filters in the API, AI MCP tools, custom email notifications and other places. |

## Who uses it

| Role                                     | Typical use                                                               |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| **Developers and integration engineers** | Pull just the records an integration needs                                |
| **Analysts and security managers**       | Export focused sets of vulnerabilities, such as overdue Critical findings |
| **Administrators**                       | Find users, groups or assets, such as users without MFA                   |
| **Automation builders**                  | Filter data in scripts and AI agents                                      |

## Send a filter

Add the filter to the request as a query parameter. Use `curl -G` with `--data-urlencode`, so the filter is encoded correctly in the URL.

| Records                                            | Parameter         |
| -------------------------------------------------- | ----------------- |
| Vulnerabilities                                    | `q_vulnerability` |
| Writeups (vulnerability library) and other records | `q`               |

{% hint style="info" %}
Check the [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started) for the correct query parameter for the API you are using
{% endhint %}

## Vulnerability examples

Each example uses this command, with the filter in place of `FILTER`:

```
curl -G -X GET 'https://demo.attackforge.com/api/ss/vulnerabilities' --data-urlencode 'q_vulnerability=FILTER' -H 'X-SSAPI-KEY: ********'
```

| Example                                                             | Filter                                                                                                                                        |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Critical or High vulnerabilities                                 | `{ priority: { $in: ["Critical", "High" ] } }`                                                                                                |
| 2. Open Critical or Open High vulnerabilities                       | `{ $and: [ { priority: { $in: [ "Critical", "High" ] } }, { status: { $eq: "Open" } } ] }`                                                    |
| 3. Critical or High vulnerabilities that are ready for retest       | `{ $and: [ { priority: { $in: [ "Critical", "High" ] } }, { is_retest: { $eq: "Yes" } } ] }`                                                  |
| 4. Critical or High vulnerabilities discovered in the last 24 hours | `{ $and: [ { priority: { $in: [ "Critical", "High" ] } }, { status: { $eq: "Open" } }, { created: { $gte: datetime("now", "-1 days") } } ] }` |

## Writeup examples

Each example uses this command, with the filter in place of `FILTER`:

```
curl -G -X GET 'https://demo.attackforge.com/api/ss/library' --data-urlencode 'q=FILTER' -H 'X-SSAPI-KEY: ********'
```

| Example                                          | Filter                                                                                     |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| 5. Writeups titled SQL Injection                 | `{title: { $eq: "SQL Injection" }}`                                                        |
| 6. Writeups tagged pluginID:53360                | `{tags: { $in: ["pluginID:53360"] }}`                                                      |
| 7. Writeups whose NessusID custom field is 53360 | `{custom_fields: { $elemMatch: { name: { $eq: "NessusID" }, value: { $eq: "53360" } } } }` |

{% hint style="info" %}
**Note:** These commands use single quotes, which work on Linux and macOS. In Windows Command Prompt, use double quotes and escape the quotes inside the filter, as in [Exporting to CSV](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api/exporting-to-csv).
{% endhint %}

## Write a filter

A filter is a set of conditions. Each condition names a field and an operator:

```
{ priority: { $eq: "Critical" } }
```

### Syntax rules

The filter looks like JSON, but isn't. Follow these rules:

| Rule                                           | Right                                                   | Wrong                                                |
| ---------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------- |
| Don't quote field names or operators           | `{ status: { $eq: "Open" } }`                           | `{ "status": { "$eq": "Open" } }`                    |
| Every field needs an operator                  | `{ status: { $eq: "Open" } }`                           | `{ status: "Open" }`                                 |
| Quote text values                              | `{ priority: { $eq: "Critical" } }`                     | `{ priority: { $eq: Critical } }`                    |
| Don't quote numbers, `true`, `false` or `null` | `{ severity: { $gte: 7 } }`                             | `{ severity: { $gte: "7" } }`                        |
| Don't quote regular expressions                | `{ title: { $regex: /SQL/i } }`                         | `{ title: { $regex: "/SQL/i" } }`                    |
| Don't quote functions                          | `{ created: { $gt: datetime("now", "-7 days") } }`      | `{ created: { $gt: "datetime('now', '-7 days')" } }` |
| Wrap IDs in `ObjectId()`                       | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }` | `{ id: { $eq: "62a190f7793b8ccd085e0d9d" } }`        |

Two or more fields in the same filter must all match, as if joined with `$and`.

### Operators

| Operator     | Matches when                                         | Example                                                                                 |
| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `$and`       | All the conditions match                             | `$and: [ { status: { $eq: "Open" } }, { priority: { $eq: "Critical" } } ]`              |
| `$or`        | Any of the conditions match                          | `$or: [ { priority: { $eq: "Critical" } }, { priority: { $eq: "High" } } ]`             |
| `$nor`       | None of the conditions match.                        | `{ $nor: [ { status: { $eq: "Closed" } }, { priority: { $eq: "Info" } } ] }`            |
| `$eq`        | The field equals the value                           | `{ priority: { $eq: "Critical" } }`                                                     |
| `$ne`        | The field doesn't equal the value                    | `{ priority: { $ne: "Info" } }`                                                         |
| `$in`        | The field matches any value in the list              | `{ tags: { $in: ["OWASP Top 10"] } }`                                                   |
| `$nin`       | The field matches none of the values in the list     | `{ tags: { $nin: ["OWASP Top 10"] } }`                                                  |
| `$all`       | A list field contains every value in the list        | `{ tags: { $all: ["CWE-520", "Web App"] } }`                                            |
| `$gt`        | The field is greater than the value                  | `{ likelihood_of_exploitation: { $gt: 7 } }`                                            |
| `$gte`       | The field is greater than or equal to the value      | `{ likelihood_of_exploitation: { $gte: 7 } }`                                           |
| `$lt`        | The field is less than the value                     | `{ likelihood_of_exploitation: { $lt: 7 } }`                                            |
| `$lte`       | The field is less than or equal to the value         | `{ likelihood_of_exploitation: { $lte: 7 } }`                                           |
| `$regex`     | The field matches a JavaScript regular expression    | `{ title: { $regex: /SQL/i } }`                                                         |
| `$options`   | Sets regular expression flags separately.            | `{ title: { $regex: /SQL/, $options: "i" } }`                                           |
| `$exists`    | The field is present (`true`) or missing (`false`).  | `{ sla: { $exists: true } }`                                                            |
| `$elemMatch` | An item in a list matches all the conditions         | `{ custom_fields: { $elemMatch: { name: { $eq: "is_pci" }, value: { $eq: "Yes" } } } }` |
| `$not`       | The condition doesn't match, or the field is missing | `{ custom_fields: { $not: { $elemMatch: { name: { $eq: "incident_number" } } } } }`     |

{% hint style="info" %}
**Note:** `$not` must sit inside a field, never at the start of the filter. To say "none of these", use `$nor` or `$ne` and `$nin`.
{% endhint %}

The `$and` and `$or` examples are shown without outer braces, as on the current page. Wrap them in `{ }` when you use them.

### Filter on custom fields and tags

Custom fields and custom tags are lists of name and value pairs, so use `$elemMatch`:

| To find records where                      | Filter                                                                                       |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
| A custom field has a specific value        | `{ custom_fields: { $elemMatch: { name: { $eq: "is_pci" }, value: { $eq: "Yes" } } } }`      |
| A custom field has any value               | `{ custom_fields: { $elemMatch: { name: { $eq: "is_pci" }, value: { $regex: /.*/i } } } }`   |
| A list custom field has at least one value | `{ custom_fields: { $elemMatch: { name: { $eq: "cwes" }, "value.0": { $exists: true } } } }` |
| A custom field isn't set                   | `{ custom_fields: { $not: { $elemMatch: { name: { $eq: "incident_number" } } } } }`          |

### Filter by date and time

Use the `datetime()` function to compare dates:

```
datetime(timeValue, modifiers, "isostring")
```

* **timeValue:** `now`, `YYYY-MM-DD`, or `YYYY-MM-DD HH:MM` (UTC).
* **modifiers** (optional): `+999 years`, `-999 years`, `+999 months`, `-999 months`, `+999 days`, `-999 days`, `+999 hours`, `-999 hours`, `+999 minutes`, `-999 minutes`, `start of year`, `start of month`, `start of day`. They're applied in order.
* **"isostring"** (optional): add this last when the field stores its date as an ISO 8601 string, such as `start_date` and `end_date` on projects, or a date custom field.

{% hint style="info" %}
**Important:** Include the `+` or `-` sign in every modifier.
{% endhint %}

| To find records                                                           | Filter                                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Created after 1 June 2022                                                 | `{ created: { $gt: datetime("2022-06-01") } }`                            |
| Created after 12:00 UTC on 1 June 2022                                    | `{ created: { $gt: datetime("2022-06-01 12:00") } }`                      |
| Created in the last 7 days                                                | `{ created: { $gt: datetime("now", "-7 days") } }`                        |
| With an SLA more than 7 days away                                         | `{ sla: { $gt: datetime("now", "+7 days") } }`                            |
| With an SLA more than 1 year and 7 days away                              | `{ sla: { $gt: datetime("now", "+7 days", "+1 year") } }`                 |
| With a custom date field (stored as an ISO string) within the last 7 days | `{ some_custom_field: { $gt: datetime("now", "-7 days", "isostring") } }` |

## Fields you can filter on

### Vulnerabilities

| Field                        | What it holds                             | Example                                                                                                                                                                       |
| ---------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | The vulnerability's ID                    | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                                                                                                       |
| `alternate_id`               | The code-based ID set on the project      | `{ alternate_id: { $eq: "GLOBEX-1" } }`                                                                                                                                       |
| `created`                    | When it was created                       | `{ created: { $gte: datetime("now", "-7 days") } }`                                                                                                                           |
| `modified`                   | When it was last changed                  | `{ modified: { $gte: datetime("now", "-7 days") } }`                                                                                                                          |
| `priority`                   | Critical, High, Medium, Low or Info       | `{ priority: { $eq: "Critical" } }`                                                                                                                                           |
| `title`                      | The title                                 | `{ title: { $regex: /SQL/i } }`                                                                                                                                               |
| `zero_day`                   | Whether it's a zero-day                   | `{ zero_day: { $eq: "Yes" } }`                                                                                                                                                |
| `likelihood_of_exploitation` | From 1 to 10                              | `{ likelihood_of_exploitation: { $gte: 7 } }`                                                                                                                                 |
| `status`                     | Open or Closed                            | `{ status: { $eq: "Open" } }`                                                                                                                                                 |
| `resolution`                 | Risk Accepted, Unresolved, Fixed or Other | `{ resolution: { $eq: "Risk Accepted" } }`                                                                                                                                    |
| `status_updated`             | When the status last changed              | `{ status_updated: { $gte: datetime("now", "-7 days") } }`                                                                                                                    |
| `is_retest`                  | Whether it's ready for retest             | `{ is_retest: { $eq: "Yes" } }`                                                                                                                                               |
| `sla`                        | The SLA due date                          | `$and: [ { status: { $eq: "Open" } }, { sla: { $lte: datetime("now", "-7 days") } } ]`                                                                                        |
| `target_remediation_date`    | The target remediation date               | `$and: [ { status: { $eq: "Open" } }, { target_remediation_date: { $lte: datetime("now", "+7 days") } }, { target_remediation_date: { $gte: datetime("now", "+6 days") } } ]` |
| `release_date`               | The release date                          | `{ release_date: { $gte: datetime("now", "-7 days") } }`                                                                                                                      |
| `tags`                       | Tags                                      | `{ tags: { $in: ["OWASP Top 10"] } }`                                                                                                                                         |
| `custom_tags`                | Custom tags (name and value)              | `{ custom_tags: { $elemMatch: { name: { $eq: "is_pci" }, value: { $eq: "Yes" } } } }`                                                                                         |
| `custom_fields`              | Custom fields (name and value)            | `{ custom_fields: { $elemMatch: { name: { $eq: "qa_passed" }, value: { $eq: "Yes" } } } }`                                                                                    |

### Writeups (vulnerability library)

| Field                        | What it holds                       | Example                                                                                     |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `id`                         | The writeup's ID                    | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                     |
| `created`                    | When it was created                 | `{ created: { $gte: datetime("now", "-7 days") } }`                                         |
| `modified`                   | When it was last changed            | `{ modified: { $gte: datetime("now", "-7 days") } }`                                        |
| `priority`                   | Critical, High, Medium, Low or Info | `{ priority: { $eq: "Critical" } }`                                                         |
| `title`                      | The title                           | `{ title: { $regex: /SQL/i } }`                                                             |
| `description`                | The description                     | `{ description: { $regex: /SQL/i } }`                                                       |
| `attack_scenario`            | The attack scenario                 | `{ attack_scenario: { $regex: /SQL/i } }`                                                   |
| `remediation_recommendation` | The remediation recommendation      | `{ remediation_recommendation: { $regex: /SQL/i } }`                                        |
| `severity`                   | From 1 to 10                        | `{ severity: { $gte: 7 } }`                                                                 |
| `likelihood_of_exploitation` | From 1 to 10                        | `{ likelihood_of_exploitation: { $gte: 7 } }`                                               |
| `category`                   | The category                        | `{ category: { $eq: "Web App" } }`                                                          |
| `impact_on_confidentiality`  | The impact on confidentiality       | `{ impact_on_confidentiality: { $in: ["High"] } }`                                          |
| `impact_on_integrity`        | The impact on integrity             | `{ impact_on_integrity: { $in: ["High"] } }`                                                |
| `impact_on_availability`     | The impact on availability          | `{ impact_on_availability: { $in: ["High"] } }`                                             |
| `import_source`              | Where it was imported from          | `{ import_source: { $eq: "Nessus" } }`                                                      |
| `import_source_id`           | Its ID in the import source         | `{ import_source_id: { $eq: "53360" } }`                                                    |
| `tags`                       | Tags                                | `{ tags: { $in: ["pluginID:53360"] } }`                                                     |
| `custom_tags`                | Custom tags (name and value)        | `{ custom_tags: { $elemMatch: { name: { $eq: "is_pci" }, value: { $eq: "Yes" } } } }`       |
| `custom_fields`              | Custom fields (name and value)      | `{ custom_fields: { $elemMatch: { name: { $eq: "NessusID" }, value: { $eq: "53360" } } } }` |

### Projects

| Field           | What it holds                        | Example                                                                                          |
| --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `id`            | The project's ID                     | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                          |
| `created`       | When it was created                  | `{ created: { $gte: datetime("now", "-7 days") } }`                                              |
| `modified`      | When it was last changed             | `{ modified: { $gte: datetime("now", "-7 days") } }`                                             |
| `name`          | The name                             | `{ name: { $eq: "ACME Corp" } }`                                                                 |
| `code`          | The project code                     | `{ code: { $regex: /9999/ } }`                                                                   |
| `start_date`    | The start date. Needs `"isostring"`. | `{ start_date: { $gte: datetime("now", "-7 days", "isostring") } }`                              |
| `end_date`      | The end date. Needs `"isostring"`.   | `{ end_date: { $gte: datetime("now", "-7 days", "isostring") } }`                                |
| `group_names`   | The project's groups                 | `{ group_names: { $in: ["ACME Developers"] } }`                                                  |
| `status`        | The project status                   | `{ status: { $eq: "Completed" } }`                                                               |
| `org_code`      | The organisation code                | `{ org_code: { $regex: /ACME1/i } }`                                                             |
| `vuln_code`     | The vulnerability code               | `{ vuln_code: { $eq: "ACME18" } }`                                                               |
| `custom_tags`   | Custom tags (name and value)         | `{ custom_tags: { $elemMatch: { name: { $eq: "is_pci" }, value: { $eq: "Yes" } } } }`            |
| `custom_fields` | Custom fields (name and value)       | `{ custom_fields: { $elemMatch: { name: { $eq: "exported_to_jira" }, value: { $eq: "No" } } } }` |

### Project requests

| Field            | What it holds                                  | Example                                                                                                 |
| ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `id`             | The request's ID                               | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                                 |
| `created`        | When it was created                            | `{ created: { $gte: datetime("now", "-7 days") } }`                                                     |
| `created_by`     | The ID of the user who created it              | `{ created_by: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                         |
| `last_modified`  | When it was last changed                       | `{ last_modified: { $gte: datetime("now", "-7 days") } }`                                               |
| `name`           | The project name                               | `{ name: { $eq: "ACME Corp" } }`                                                                        |
| `code`           | The project code                               | `{ code: { $regex: /9999/ } }`                                                                          |
| `start_date`     | The requested start date. Needs `"isostring"`. | `{ start_date: { $gte: datetime("now", "-7 days", "isostring") } }`                                     |
| `end_date`       | The requested end date. Needs `"isostring"`.   | `{ end_date: { $gte: datetime("now", "-7 days", "isostring") } }`                                       |
| `status`         | The request status                             | `{ status: { $eq: "Pending Approval" } }`                                                               |
| `org_code`       | The organisation code                          | `{ org_code: { $regex: /ACME1/i } }`                                                                    |
| `justification`  | The justification                              | `{ justification: { $regex: /ACME1/i } }`                                                               |
| `onsite_testing` | Whether onsite testing is needed               | `{ onsite_testing: { $eq: "Yes" } }`                                                                    |
| `test_window`    | The test window                                | `{ test_window: { $regex: /Mon-Fri \(Business Hours\)/i } }`                                            |
| `custom_fields`  | Custom fields (name and value)                 | `{ custom_fields: { $elemMatch: { name: { $eq: "production_environment" }, value: { $eq: "Yes" } } } }` |

### Assets

| Field                | What it holds                               | Example                                                                                     |
| -------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `id`                 | The asset's ID                              | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                     |
| `created`            | When it was created                         | `{ created: { $gte: datetime("now", "-7 days") } }`                                         |
| `modified`           | When it was last changed                    | `{ modified: { $gte: datetime("now", "-7 days") } }`                                        |
| `name`               | The name                                    | `{ name: { $eq: "ACME Corp" } }`                                                            |
| `type`               | The asset type                              | `{ type: { $eq: "Web App" } }`                                                              |
| `details`            | The details                                 | `{ details: { $regex: /Used for XYZ/i } }`                                                  |
| `external_id`        | An ID from another system, such as SNOW-123 | `{ external_id: { $eq: "SNOW-123" } }`                                                      |
| `asset_library_keys` | The asset libraries it's in                 | `{ asset_library_keys: { $in: [ ObjectId("662f1bafcdd044fcc3e4e28d") ] } }`                 |
| `custom_fields`      | Custom fields (name and value)              | `{ custom_fields: { $elemMatch: { name: { $eq: "from_cmdb" }, value: { $eq: "SNOW" } } } }` |

### Groups

| Field                    | What it holds                       | Example                                                                                         |
| ------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `id`                     | The group's ID                      | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                         |
| `created`                | When it was created                 | `{ created: { $gte: datetime("now", "-7 days") } }`                                             |
| `modified`               | When it was last changed            | `{ modified: { $gte: datetime("now", "-7 days") } }`                                            |
| `name`                   | The name                            | `{ name: { $eq: "Parks Department" } }`                                                         |
| `owner`                  | The owner                           | `{ owner: { $eq: "Ron Swanson" } }`                                                             |
| `primary_contact_name`   | The primary contact's name          | `{ primary_contact_name: { $eq: "Leslie Knope" } }`                                             |
| `primary_contact_number` | The primary contact's phone number  | `{ primary_contact_number: { $eq: "+1 555 555 5555" } }`                                        |
| `primary_contact_email`  | The primary contact's email address | `{ primary_contact_email: { $eq: "leslie.knope@parksandrecreation.pawnee.gov" } }`              |
| `custom_fields`          | Custom fields (name and value)      | `{ custom_fields: { $elemMatch: { name: { $eq: "type" }, value: { $eq: "Internal Team" } } } }` |

### Users

Only administrators can filter on the fields marked *Admin only*.

| Field                  | What it holds                                          | Example                                                                                           |
| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `id`                   | The user's ID                                          | `{ id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") } }`                                           |
| `first_name`           | First name                                             | `{ first_name: { $eq: "Ron" } }`                                                                  |
| `last_name`            | Last name                                              | `{ last_name: { $eq: "Swanson" } }`                                                               |
| `email_address`        | Email address                                          | `{ email_address: { $eq: "ron.swanson@parksandrecreation.pawnee.gov" } }`                         |
| `username`             | Username                                               | `{ username: { $eq: "ron.swanson@parksandrecreation.pawnee.gov" } }`                              |
| `custom_fields`        | Custom fields (name and value)                         | `{ custom_fields: { $elemMatch: { name: { $eq: "type" }, value: { $eq: "External Vendor" } } } }` |
| `mfa_enabled`          | *Admin only.* Whether MFA is on                        | `{ mfa_enabled: { $eq: "No" } }`                                                                  |
| `role`                 | *Admin only.* The user's role                          | `{ role: { $eq: "admin" } }`                                                                      |
| `created`              | *Admin only.* When the user was created                | `{ created: { $gte: datetime("now", "-7 days") } }`                                               |
| `modified`             | *Admin only.* When the user was last changed           | `{ modified: { $gte: datetime("now", "-7 days") } }`                                              |
| `account_expiry`       | *Admin only.* When the account expires, if set         | `{ account_expiry: { $lte: datetime("now", "+7 days") } }`                                        |
| `failed_logins`        | *Admin only.* Failed login attempts                    | `{ failed_logins: { $gte: 1 } }`                                                                  |
| `is_deleted`           | *Admin only.* Whether the user is deleted              | `{ is_deleted: { $eq: "Yes" } }`                                                                  |
| `last_active_on_app`   | *Admin only.* When they were last active in the app    | `{ last_active_on_app: { $gte: datetime("now", "-7 days") } }`                                    |
| `last_active_on_ssapi` | *Admin only.* When they last used the Self-Service API | `{ last_active_on_ssapi: { $gte: datetime("now", "-7 days") } }`                                  |
| `last_logged_in`       | *Admin only.* When they last logged in                 | `{ last_logged_in: { $gte: datetime("now", "-7 days") } }`                                        |
| `status`               | *Admin only.* The account status                       | `{ status: { $eq: "Blocked" } }`                                                                  |

## Tips

* **Start simple.** Get one condition working, then add more.
* **Use `$in` for several values of one field.** `{ priority: { $in: ["Critical", "High"] } }` is shorter than an `$or`.
* **Use relative dates.** `datetime("now", "-7 days")` stays correct every time you run the filter, unlike a fixed date.
* **Add `"isostring"` for date custom fields** and for project `start_date` and `end_date`.
* **Make text matches case-insensitive.** Add the `i` flag: `/sql/i`.
* **Wrap IDs in `ObjectId()`.** A plain ID string won't match.
* **Encode the filter.** Use `curl -G --data-urlencode` so characters such as `$`, `{` and spaces arrive intact.
* **Test with a count first.** If the method has a count equivalent, or the [AI MCP](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills) `count_*` tools, check how many records match before you fetch them.

## FAQ

**Which API methods accept a filter?** Only some. Check each method in the [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started).

**Should I use `q` or `q_vulnerability`?** Use `q_vulnerability` for vulnerabilities, and `q` for writeups. Check the method's documentation for other records.

**Why does my filter return an error?** The most common causes are quoted field names or operators, a field with no operator (`{ status: "Open" }`), and quoted functions or regular expressions. See Syntax rules.

**Why does my filter return nothing?** Check the field name and value, including capitals: `"Critical"`, not `"critical"`. Use `$regex` with the `i` flag to ignore case.

**Can I filter on custom fields?** Yes. Use `$elemMatch` on `custom_fields` or `custom_tags`, with the field's key as `name`.

**How do I find records where a custom field is empty?** Use `$not` with `$elemMatch`. See Filter on custom fields and tags.

**What time zone does `datetime()` use?** UTC.

**Why can't I filter users on `role` or `mfa_enabled`?** Those fields are only available to administrators.

**Is this the same as MongoDB?** It's similar, but supports only the operators on this page. Every field also needs an operator, so there's no `{ field: value }` shorthand.

## Related pages

* [Self-Service RESTful API](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api): get access to API methods and create your API key.
* [Exporting to CSV](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api/exporting-to-csv): export filtered vulnerabilities to a spreadsheet.
* [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started): which methods accept filters, and their fields.
* [AI MCP and Skills](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills): MCP tools use the same filter syntax.
* [MDN: Regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions): the syntax for `$regex`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api/advanced-query-filter.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.