Filtering

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

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)

in and nin are legacy aliases for in_any and nin_any. Prefer the canonical names.

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:

# 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:

# 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.

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.

Combine multiple filters

Use and() to require all conditions:

# 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:

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:

# 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:

# "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:

{
  "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.

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.

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 for where a value appears in the response.

Available filters

For a complete list of all filters and sort keys grouped by scope, see the Filters & Sorting Reference. You can also fetch available filters programmatically:

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

Getting Started

Examples

Concepts

References

Agent APIs

Expression syntax

Operators

Examples

Filter by HQ country

Filter by industry (match any)

Combine multiple filters

Cross-reference filter

Enum filters

Sorting

Available filters

​Expression syntax

​Operators

​Examples

​Filter by HQ country

​Filter by industry (match any)

​Combine multiple filters

​Cross-reference filter

​Enum filters

​Sorting

​Available filters

Expression syntax

Operators

Examples

Filter by HQ country

Filter by industry (match any)

Combine multiple filters

Cross-reference filter

Enum filters

Sorting

Available filters