# Query Syntax

The `q` parameter accepts a boolean query, and it works the same on news, blogs, and forums. Terms without a field prefix are matched against the post title, text, and thread title. A space between terms means **AND**.

## Operators

| Syntax | Example | Matches |
| --- | --- | --- |
| Implicit AND | `solar battery` | Posts with both terms |
| `OR` | `solar OR wind` | Either term |
| `NOT` or `-` | `tesla NOT car`, `tesla -car` | First term without the second |
| `( )` | `(solar OR wind) storage` | Grouping |
| `"..."` | `"climate change"` | Exact phrase |
| `"..."~N` | `"apple watch"~3` | Terms within N words of each other |
| `*` | `crypt*` | Prefix wildcard |
| `$` | `gold$` | Exact term, no stemming. Supported for English, Spanish, Arabic, Russian, and French. |
| `field:value` | `language:english` | Field filter - see filters for [News](news-api-filters), [Blogs](blogs-api-filters), or [Forums](forums-api-filters) |

## Examples

Company mentions, excluding job posts:

```
"acme corp" NOT (hiring OR "job opening")
```

A phrase near another term, in English news from the US:

```
"data breach"~5 ransomware language:english country:US
```

## Rules

- Quotes and parentheses must be balanced, or the request fails with `400`.
- At most **10** proximity (`~N`) operators per query.
- Leading wildcards (`*word`) are removed automatically - they are too expensive to run.
- Operators `AND`, `OR`, `NOT` must be uppercase.
- Filter values are case-insensitive; quote values that contain spaces, e.g. `author:"jane doe"`.

> [!TIP]
> Not sure about a query? Add `warning=true` to your request - potential issues come back in a `warnings` array without failing the request.