> ## Documentation Index
> Fetch the complete documentation index at: https://developers.beta.dealroom.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering

> Narrow Dealroom API results with filter expressions. Supports comparison operators, logical AND/OR, and 90+ fields across entities.

Filters use a single `filter` query parameter with an expression string:

```text theme={null}
filter=<expression>
```

## Expression syntax

| Form      | Syntax                      | Example                                                                              |
| --------- | --------------------------- | ------------------------------------------------------------------------------------ |
| Single    | `field[op]:value`           | `total_funding[gte]:1000000`                                                         |
| AND       | `and(expr,expr,...)`        | `and(total_funding[gte]:1000000,hq_location[eq]:233)`                                |
| OR        | `or(expr,expr,...)`         | `or(hq_location[eq]:118871,hq_location[eq]:1297711)`                                 |
| Nested    | `and(or(...),expr)`         | `and(or(hq_location[eq]:118871,hq_location[eq]:1297711),total_funding[gte]:1000000)` |
| Cross-ref | `relation__field[op]:value` | `investor__total_invested[gte]:100000000`                                            |

## Operators

| Operator  | Description                                 |
| --------- | ------------------------------------------- |
| `eq`      | Exact match                                 |
| `neq`     | Not equal                                   |
| `gt`      | Greater than                                |
| `gte`     | Greater than or equal                       |
| `lt`      | Less than                                   |
| `lte`     | Less than or equal                          |
| `in_any`  | Matches any of the given values             |
| `nin_any` | Matches none of the given values            |
| `in_all`  | Matches all values (relation filters only)  |
| `nin_all` | Excludes all values (relation filters only) |

<Note>
  `in` and `nin` are legacy aliases for `in_any` and `nin_any`. Prefer the
  canonical names.
</Note>

## Examples

### Filter by HQ country

Locations are matched by numeric ID from the Dealroom location taxonomy, not by
country name. Look up an ID once via `GET /reference/filters/location/values` and
reuse it:

```bash theme={null}
# Discover the ID (returns { id: 233, name: "United States", ... })
curl "https://api.beta.dealroom.app/reference/filters/location/values?q=United+States" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"

# Then filter
curl -g "https://api.beta.dealroom.app/data/entities?sort=-launch_date&filter=hq_location[eq]:233" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

### Filter by industry (match any)

Industries (and other taxonomy values) live behind the `tag_id` filter. Pass
`?type=industry` on the values endpoint to scope the lookup, then pipe-separate
the resulting IDs in the filter expression:

```bash theme={null}
# Discover IDs first — returns { id: 126403, name: "Fintech", ... } etc.
curl "https://api.beta.dealroom.app/reference/filters/tag_id/values?q=fintech&type=industry" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"

# Then filter — pipe-separate to match any of several tags
# (126403 = Fintech, 202 = Artificial Intelligence)
curl -g "https://api.beta.dealroom.app/data/entities?sort=-latest_valuation&filter=tag_id[in_any]:126403|202" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

The `type` parameter accepts: `industry`, `sub_industry`, `sector`, `technology`,
`business_model`, `income_stream`, `client_focus`, `sdg`, `ownership`,
`techstack_category`, `growth_stage`, `investor_type`.

<Warning>
  A lookup scoped to the wrong `type` returns an **empty `200`**, not an error —
  e.g. "Artificial Intelligence" is a `technology` tag, so
  `?q=artificial&type=industry` finds nothing. When unsure, omit `type` to
  search across all tag types.
</Warning>

### Combine multiple filters

Use `and()` to require all conditions:

```bash theme={null}
# 323 = Netherlands (discover via /reference/filters/location/values — never guess IDs)
curl -g "https://api.beta.dealroom.app/data/entities?sort=-launch_date&filter=and(hq_location[eq]:323,launch_date[gte]:2018,total_funding[gte]:1000000)" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

### Cross-reference filter

Filter companies by their investors' total invested amount:

```bash theme={null}
filter=investor__total_invested[gte]:100000000
```

## Enum filters

Some filters accept a value from a **fixed, closed set** rather than free text or an
ID. Discover the valid values with the values endpoint — same as `id_lookup` filters:

```bash theme={null}
# Each value has the shape { id, code, name, entity_count },
# e.g. { "id": 2, "code": "series_a", "name": "SERIES A", "entity_count": 4210 }
curl "https://api.beta.dealroom.app/reference/filters/round_type/values" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

You can commit either the `name` (`SERIES A`) or its `code` (`series_a`) as the filter value.

The following enum filters match **case-insensitively** and **reject unknown values** with
a `400 FILTER_VALIDATION_ERROR` (rather than silently returning no results):

| Filter            | Used on                            |
| ----------------- | ---------------------------------- |
| `round_type`      | `/data/transactions`, `/data/news` |
| `preferred_round` | `/data/investors`                  |
| `investor_type`   | `/data/investors`                  |
| `article_type`    | `/data/news`                       |

Because matching is case-insensitive, `series a` and `SERIES A` are equivalent:

```bash theme={null}
# "series a" resolves to the canonical "SERIES A"
curl -g "https://api.beta.dealroom.app/data/transactions?filter=round_type[eq]:series%20a" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

A value outside the set returns an error instead of an empty result — see
[Errors](/concepts/errors):

```json theme={null}
{
  "error": {
    "code": "FILTER_VALIDATION_ERROR",
    "message": "Invalid value for filter 'round_type': \"seriesa\". See /reference/filters/round_type/values for accepted values.",
    "details": { "filter": "round_type" }
  }
}
```

## Sorting

Use the `sort` parameter with a field name. Prefix with `-` for descending order.

```text theme={null}
sort=-launch_date      # newest first
sort=-total_funding    # highest funded first
```

The full list of accepted sort keys per resource is in the
[Filters & Sorting Reference](/references/filters-and-sorting).

<Note>
  A sort or filter key doesn't always match a top-level response field.
  `total_funding`, for example, sorts and filters companies by the value
  returned at `funding_summary.total_funding` — there is no top-level
  `total_funding` field on the entity. Check the object pages in the
  [API Reference](/api-reference) for where a value appears in the response.
</Note>

## Available filters

For a complete list of all filters and sort keys grouped by scope, see the
[Filters & Sorting Reference](/references/filters-and-sorting).

You can also fetch available filters programmatically:

```bash theme={null}
curl "https://api.beta.dealroom.app/reference/filters?scope=companies" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```