> ## Documentation Index
> Fetch the complete documentation index at: https://docs.data.avina.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Three ways to search

> Plain language, free-text criteria and structured filters, and when to use each.

Every search answers the same question: which companies, or people, meet all of these requirements? You can state the requirements in three ways.

| | `query` | `criteria` | `filters` |
| - | - | - | - |
| **What it is** | A sentence or paragraph in plain language | A list of free-text requirements | Exact conditions on named fields |
| **Example** | `"Private dental practices in Texas hiring SDRs"` | `["independently owned", "offers same-day implants"]` | `company.employee_count between [10, 200]` |
| **How it is checked** | Turned into `filters` and `criteria`, which are then checked | Against the company's own description and the public web | Against structured data records |
| **Best for** | End-user input, agents, exploration | Anything no field can express | Repeatable pipelines, exact control |

Send `query` on its own, or send `filters` and `criteria` together. A request with `query` plus `filters` or `criteria` is rejected with `400 invalid_request`.

## Plain language

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "query": "Privately held dental practices in Texas hiring SDRs", "limit": 20 }
```

Avina turns the sentence into structured filters and free-text criteria, then runs the search. (An SDR is a sales development representative: a salesperson who finds and qualifies new prospects.) The search's `interpretation` field shows exactly how the sentence was read:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "interpretation": {
    "filters": {
      "all": [
        { "field": "company.industry", "operator": "in", "value": ["Dentists"] },
        { "field": "company.business_description", "operator": "matches", "value": "dental practices" },
        { "field": "company.headquarters.state", "operator": "in", "value": ["Texas"] },
        { "field": "company.type", "operator": "in", "value": ["Privately Held"] },
        { "related": { "relationship": "open_jobs", "where": { "all": [
          { "field": "title", "operator": "in", "value": ["Sales Development Representative", "SDR"] }
        ] } } }
      ]
    },
    "criteria": [],
    "unsupported_criteria": []
  },
  "assumptions": []
}
```

Interpretation follows three rules:

* **Nothing is dropped.** Every requirement in your sentence becomes a filter or a criterion. A requirement is never relaxed to return more results.
* **Ambiguity is reported, not hidden.** When a phrase has more than one reasonable reading, Avina picks the likeliest and lists it under `assumptions`, with the alternatives. The search still runs. Reword the query if the reading is wrong.
* **Requirements that cannot be checked stop the search.** Things no public source can confirm, such as "visited our pricing page" or "has a great culture", are listed under `unsupported_criteria`. The search ends with `stop_reason: query_needs_clarification` before any provider is called, and nothing is charged.

For example, "recently" has no fixed meaning, so a query for "recently funded fintech companies in New York" reports how it was read:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "assumptions": [
    {
      "text": "recently funded",
      "assumed": "Last funding round was within the last 90 days",
      "alternatives": ["Last funding round was within the last 12 months"]
    }
  ]
}
```

> [!TIP]
>
> To see how a query will be read before spending anything, send it to [Parse](https://docs.data.avina.io/capabilities/parse.md). It returns the same interpretation and a ready-to-send structured request.

## Structured filters

Filters are exact conditions on named fields. Use them when you know precisely what you want and need the request to mean the same thing every time.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.headquarters.country", "operator": "in", "value": ["US"] },
      { "field": "company.employee_count", "operator": "between", "value": [10, 200] },
      { "field": "company.total_funding", "operator": "gte", "value": { "amount": 5000000, "currency": "USD" } }
    ]
  }
}
```

A company must meet every condition in `all`. Conditions cover company facts (industry, location, employee count, revenue, company type, founding year), funding (total raised, last round, how recent), technologies in use, and two kinds of activity: open jobs and recent hires.

The [filter reference](https://docs.data.avina.io/guides/structured-filters.md) lists every field, operator and value format.

## Free-text criteria

Criteria cover what no field can express. Each one is a statement that must be true of a match, and each is checked separately against evidence.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": { "all": [{ "field": "company.industry", "operator": "in", "value": ["Dentists"] }] },
  "criteria": [
    { "text": "independently owned, not part of a dental support organization", "kind": "attribute" },
    { "text": "opened a new location this year", "kind": "event" }
  ]
}
```

| `kind` | Use for | How it is checked |
| - | - | - |
| `attribute` | A lasting fact the company would state about itself: "sells to hospitals", "manufactures industrial heat pumps" | Against the company's own description, then the web |
| `event` | Something that happened: "opened a location in Texas this year", "announced a partnership with Stripe" | Web research with sources |

A plain string is treated as an `event`. A search takes at most 10 criteria.

> [!TIP]
>
> Write each criterion as one statement that can be checked. "B2B SaaS company that sells to hospitals and recently raised funding" is three requirements: an industry filter, an `attribute` criterion and a funding filter. Splitting them gives clearer evidence for each.

## How they combine

All requirements are combined with AND. A company is returned only when it matches every filter condition and every criterion. There is no relevance score that lets a strong match on one requirement make up for failing another.

To express OR on one field, put the alternatives in a single `in` list:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "field": "company.headquarters.country", "operator": "in", "value": ["US", "CA", "GB"] }
```

## Choosing between them

> [accordion] You are building a search box for end users
>
> Send their text as `query`. Show `assumptions` next to the results so users can correct a wrong reading. Or call [Parse](https://docs.data.avina.io/capabilities/parse.md) first and render the filters as editable chips.

> [accordion] You are giving an agent a search tool
>
> Let the agent send `query`. Have it read `interpretation` and `assumptions` from the status response and reword if the reading is off.

> [accordion] You run the same search on a schedule
>
> Send `filters` and `criteria`. A structured request is interpreted the same way every time. Use [Parse](https://docs.data.avina.io/capabilities/parse.md) once to draft it, then store and edit the result.

> [accordion] Your requirement is not a field
>
> Keep the structured parts as `filters` and add the rest as `criteria`.

## Next steps

> [card] [Filter reference](https://docs.data.avina.io/guides/structured-filters.md)
>
> Every field, operator and value format.

> [card] [Evidence and verdicts](https://docs.data.avina.io/concepts/evidence.md)
>
> How each requirement is checked and reported.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.