> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aventure.vc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aventure.vc/_mcp/server.

# Refine entity filter options

POST https://api.aventure.vc/v1/entities/filters/refine
Content-Type: application/json

Return filter metadata scoped by current filters. Each filter entry reports choiceOptionTotal and choiceOptionTruncated so CLI and MCP callers can tell when the displayed choiceOption list is only the top scoped subset. Use the filter search endpoint with the same scopeFilter to look up values not shown in the refine response.

Reference: https://docs.aventure.vc/api-reference/a-venture-api/entity-filters/refined

## Authentication

- `X-Client-Secret` header (required) — Client secret for read-only service-to-service access (no writes)

## Request

### Body (application/json)

- `acceleratorBrand` (list of string, optional) — Accelerator brand or operator name.
- `acceleratorCohort` (list of string, optional) — Accelerator batch or cohort label.
- `acceleratorName` (list of string, optional) — Specific accelerator program name.
- `acceleratorStatus` (list of string, optional) — Accelerator participation status.
- `affinity` (list of string, optional) — Affinity provider organization names accepted by the companies list filter. Affinity rows are member -> provider; use provider names here, not member names.
- `employeeCountRange` (list of object, optional) — Inclusive reported employee-count ranges, in employees.
  - `max` (integer, optional, nullable) — Inclusive maximum integer.
  - `min` (integer, optional, nullable) — Inclusive minimum integer.
- `entityId` (list of string, optional) — Restrict results to specific entity IDs.
- `entityName` (list of string, optional) — Exact normalized match against entity brand or legal names.
- `featured` (boolean, optional, nullable) — Filter by featured status.
- `fundraiseActivity` (object, optional) — Fundraise activity
  - `amountInvestedRange` (list of object, optional)
    - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
    - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
  - `amountRaisedRange` (list of object, optional)
    - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
    - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
  - `investedCompanyName` (list of string, optional) — Portfolio company names. Exact, case-sensitive match on the portfolio company's brand or legal name; restricts returned entities to investors in those companies.
  - `investorActivity` (object, optional) — Aggregate investor activity filters.
    - `averageAmountInvestedUsdRange` (list of object, optional)
      - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
      - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
    - `largestAmountInvestedUsdRange` (list of object, optional)
      - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
      - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
    - `smallestAmountInvestedUsdRange` (list of object, optional)
      - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
      - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
    - `totalAmountInvestedUsdRange` (list of object, optional)
      - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
      - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
    - `totalInvestmentRange` (list of object, optional)
      - `max` (integer, optional, nullable) — Inclusive maximum integer.
      - `min` (integer, optional, nullable) — Inclusive minimum integer.
  - `lastRoundYearRange` (list of object, optional)
    - `max` (integer, optional, nullable) — Inclusive maximum integer.
    - `min` (integer, optional, nullable) — Inclusive minimum integer.
  - `round` (list of string, optional) — Fundraise round labels, such as Seed or Series A.
  - `totalRaisedRange` (list of object, optional)
    - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
    - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
  - `valuationRange` (list of object, optional)
    - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78.
    - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78.
- `hasFundraising` (boolean, optional, nullable) — Filter to entities with fundraise activity.
- `headquartersCity` (list of string, optional) — Headquarters city values.
- `headquartersCountry` (list of string, optional) — Headquarters country values.
- `headquartersState` (list of string, optional) — Headquarters state or region values.
- `industry` (list of string, optional) — Industry classification values.
- `letter` (string, optional, nullable) — First letter of the display name.
- `location` (list of string, optional) — Geographic classification values.
- `logoOption` (object, optional) — Logo sort priority.
  - `sortPriority` (enum, required) — Logo sort priority.
    - Allowed values: `NONE`, `ANY_LOGO_FIRST`, `REAL_LOGO_FIRST`
- `mainProduct` (list of string, optional) — Main product classification values.
- `operatingStatus` (list of string, optional) — Operating status values.
- `portfolioHeadquartersCity` (list of string, optional) — Portfolio-company headquarters city values.
- `portfolioHeadquartersCountry` (list of string, optional) — Portfolio-company headquarters country values.
- `portfolioHeadquartersState` (list of string, optional) — Portfolio-company headquarters state or region values.
- `qualityGate` (enum, optional) — Named server-owned list quality gate.
  - Allowed values: `NONE`, `COMPANY_LISTING_READY`
- `semanticQuery` (string, optional, nullable) — Semantic entity search phrase.
- `slug` (list of string, optional) — Restrict results to entity slugs.
- `stage` (list of string, optional) — Investment stage classification values.
- `suppressNonOperating` (boolean, optional, nullable) — Suppress entities with terminal operating status.
- `suppressZeroTotalRaised` (boolean, optional, nullable) — Suppress entities whose total raised is zero.
- `tag` (list of string, optional) — General classification tag values.
- `textSearch` (string, optional, nullable) — Non-blank keyword/full-text search term. Use natural-search for plain-English or multi-constraint company requests.
- `typeCustomer` (list of string, optional) — Customer-type classification values.
- `typeModel` (list of string, optional) — Business-model classification values.
- `typeOwnership` (list of string, optional) — Ownership-model classification values.
- `typeRecord` (list of enum, optional) — Entity type filter. Organization expands to Company, Investment Firm, Nonprofit, and Government; omit to include every entity type.
  - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
- `typeRevenue` (list of string, optional) — Revenue-model classification values.
- `typeTechnologyUsed` (list of string, optional) — Technology-used classification values.
- `url` (string, optional, nullable) — Current URL to match by normalized host and path.
- `urlDomain` (string, optional, nullable) — Current root domain to match when urlMatchMode=domain.
- `urlMatchMode` (enum, optional) — URL matching mode: hostPath uses host and path; domain uses the root domain.
  - Allowed values: `hostPath`, `domain`
- `urlType` (enum, optional, nullable) — Restrict URL matching to one URL type.
  - Allowed values: `website`, `linkedin`, `twitter`, `github`, `facebook`, `instagram`, `tiktok`, `youtube`, `subreddit`, `forum`, `documentation`, `support`, `statuspage`, `changelog`, `roadmap`, `discord`, `crunchbase`, `wellfound`, `angellist`, `glassdoor`, `theorg`, `ycombinator`, `wikipedia`, `pitchbook`, `morningstar`, `bloomberg`, `nyse`, `nasdaq`, `g2`, `producthunt`, `trustpilot`, `alternativeto`, `gartnerpeerinsights`, `getapp`, `sourceforge`, `appstore`, `googleplay`, `capterra`, `trustradius`, `hubspotmarketplace`, `slackappdirectory`, `awsmarketplace`, `salesforceappexchange`, `chromewebstore`, `vscodemarketplace`, `npm`, `pypi`, `maven`, `dockerhub`, `homebrew`, `crates`
- `yearFoundedRange` (list of object, optional) — Inclusive founding-year ranges, in calendar years.
  - `max` (integer, optional, nullable) — Inclusive maximum integer.
  - `min` (integer, optional, nullable) — Inclusive minimum integer.

## Response

### 200

OK

- `filter` (list of object, required) — Canonical filter entries for the active entity scope.
  - `chart` (list of object, required) — Chart filter values
    - `amount` (long, required) — Amount
    - `end` (long, required) — Exclusive bucket end value
    - `start` (long, required) — Inclusive bucket start value
  - `choiceOption` (list of object, required) — Choice option filter values
    - `label` (string, required) — Display label for the option
    - `value` (string, required) — Canonical option value
    - `scope` (object, optional, nullable) — Optional numeric scope for the option
      - `max` (long, optional, nullable) — Maximum scope value
      - `min` (long, optional, nullable) — Minimum scope value
  - `controlType` (enum, required) — Control type used to render the filter
    - Allowed values: `checkbox`, `range`, `currencyRange`, `dateRange`
  - `filterKey` (string, required) — Canonical filter key
  - `label` (string, required) — Display label for the filter
  - `choiceOptionTotal` (integer, optional, nullable) — Total eligible choice option values for this filter
  - `choiceOptionTruncated` (boolean, optional, nullable) — Whether additional eligible choices exist beyond choiceOption
  - `filterMeta` (object, optional, nullable) — Optional entity-specific filter metadata
    - `ui` (object, optional, nullable) — UI metadata for rendering entity filter controls
      - `headquartersOption` (object, optional, nullable) — Headquarters option hierarchy
        - `country` (list of object, required) — Countries with their states and cities
          - `country` (string, required) — Country name
          - `state` (list of object, required) — States within the country
            - `city` (list of string, required) — Cities within the state; empty when only states were requested
            - `state` (string, required) — State name
  - `scope` (object, optional, nullable) — Optional numeric scope for the filter
    - `max` (long, optional, nullable) — Maximum scope value
    - `min` (long, optional, nullable) — Minimum scope value
- `meta` (object, required) — Pagination and degradation state for this refinement.
  - `degraded` (boolean, required) — Whether retrying may improve scoped choice totals
  - `limit` (integer, required) — Maximum entities sampled for displayed choices.
  - `page` (integer, required) — Zero-based result page used to build the refinement.
  - `total` (integer, optional, nullable) — Total entities matching the active filter; null when unavailable.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "filter": [
    {
      "chart": [
        {
          "amount": 1,
          "end": 1,
          "start": 1
        }
      ],
      "choiceOption": [
        {
          "label": "string",
          "value": "string",
          "scope": {
            "max": 1,
            "min": 1
          }
        }
      ],
      "controlType": "checkbox",
      "filterKey": "string",
      "label": "string",
      "choiceOptionTotal": 1,
      "choiceOptionTruncated": true,
      "filterMeta": {
        "ui": {
          "headquartersOption": {
            "country": [
              {
                "country": "string",
                "state": [
                  {
                    "city": [
                      "string"
                    ],
                    "state": "string"
                  }
                ]
              }
            ]
          }
        }
      },
      "scope": {
        "max": 1,
        "min": 1
      }
    }
  ],
  "meta": {
    "degraded": true,
    "limit": 1,
    "page": 1,
    "total": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.aventure.vc/v1/entities/filters/refine"

payload = {}
headers = {
    "X-Client-Secret": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.aventure.vc/v1/entities/filters/refine';
const options = {
  method: 'POST',
  headers: {'X-Client-Secret': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aventure.vc/v1/entities/filters/refine"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Client-Secret", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.aventure.vc/v1/entities/filters/refine")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Client-Secret"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.aventure.vc/v1/entities/filters/refine")
  .header("X-Client-Secret", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.aventure.vc/v1/entities/filters/refine', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Client-Secret' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.aventure.vc/v1/entities/filters/refine");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Client-Secret", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Client-Secret": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/entities/filters/refine")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```