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.

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

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.

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