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

# List Generation API Best Practices

> Best practices for using list generation API.

**Never combine `query` and `filters` in the same request**

`query` and `filters` are mutually exclusive. Pass one or the other, not both. If you send both, the request will not resolve to a predictable result set. If you started with a natural language `query` and want to refine it, translate the criteria into an equivalent `filters` object rather than layering `filters` on top of `query`.

```python theme={null}
# ❌ Invalid — mutually exclusive parameters combined
payload = {
    "query": "SaaS companies in the US",
    "filters": {"firmographic.company_type": ["private"]}
}

# ✅ Correct — pick one
payload = {
    "filters": {
        "location.hq.country": ["USA"],
        "business_model.offering_type": ["software"],
        "firmographic.company_type": ["private"]
    }
}
```

**Resolve industry names to codes before filtering. Never pass free text to** `industry.industry`

The `industry.industry` filter expects akta.pro taxonomy industry codes, not free-text sector names like `"warehouse automation"` or `"fintech"`. Resolve the topic first with the [Industry Search API](/api-reference/supporting-apis/industry-search):

```python theme={null}
industry_code = requests.get(
    "https://api.akta.pro/api/v1/industry/search",
    headers={"x-api-key": API_KEY},
    params={"query": "warehouse automation"}
).json()["data"][0]["code"]

payload = {"filters": {"industry.industry": [industry_code]}}
```

If a topic maps to multiple closely related industries, pass several codes rather than relying on the single top match.

**Use 3-letter ISO country codes for all location filters, not country names**

`location.hq.country`, `location.market_served.markets`, and `location.offices.country` all expect 3-letter ISO alpha-3 codes (`USA`, `IND`, `GBR`), not full country names (`"United States"`). Passing a name instead of a code will not match. `location.hq.city` by contrast, take free text. `location.hq.region` takes [M49 region codes](/region-codes).

```python theme={null}
# ❌ Will not match
"location.hq.country": ["United States"]

# ✅ Correct
"location.hq.country": ["USA"]
```

**Only request the** `sections `**you actually need**

`credits_consumed` scales with the enrichment sections requested per company, not just with how many companies are returned.

**Remember `funding_detail` and `mna_and_investment` are Enterprise-only**

Both the `funding_detail`/`mna_and_investment` enrichment sections and the corresponding `funding_detail.*` structured filters require an Enterprise plan. If your plan doesn't include Enterprise access, requests using these will not return the expected data — check your plan tier before building a workflow that depends on funding-stage or investor-level filtering.

**Use `query` for exploration, `filters` for production workflows**

Natural language `query` is convenient for a first pass at an unfamiliar segment, but its interpretation can vary slightly between calls since it depends on query understanding rather than deterministic filter matching. Once you've validated that a query surfaces the right kind of companies, translate the underlying criteria into an equivalent `filters` object for any workflow you'll run repeatedly, cache, or need to audit — filters always resolve the same way given the same inputs.