Skip to main content
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.
Resolve industry names to codes before filtering — never pass free text to industry.industry The industry.industry filter expects Akta taxonomy industry codes, not free-text sector names like "warehouse automation" or "fintech". Resolve the topic first with the Industry Search API:
If a topic maps to multiple closely related industries, pass several codes rather than relying on the single top match — industry.industry matches any company carrying any of the selected codes. 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 3166-1 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 and location.hq.region, by contrast, take free text and region names respectively — check each field’s accepted format before assuming they’re interchangeable.
Understand that all filters are combined with AND logic — narrow incrementally, not all at once Every key inside the filters object must match for a company to be included in the results. Stacking many highly specific filters at once (e.g. a narrow revenue band + a narrow founding year range + a specific funding round + a specific investor) can silently return zero results if the combination doesn’t exist in the data. Start with 2–3 broad filters, check total_count, and narrow from there rather than assembling the full filter set speculatively.
Check total_count with a minimal, low-cost call before pulling a full enriched list A request with limit: 1 and no sections costs close to nothing (enrichment sections, not row count, drive credit consumption) and immediately tells you how large a segment is via total_count. Use this to validate a filter combination before committing to a full enrichment pull, especially for filters you’re not certain will match many companies.
Only request the sections you actually need — enrichment drives credit cost, not the row count credits_consumed scales with the enrichment sections requested per company, not simply with how many companies are returned. Requesting sections: ["firmographic", "business_model", "financial_estimate", "location", "technology", "management_profile", "funding_detail", ...] when you only need firmographic and location unnecessarily inflates cost. Natural language queries and filter requests with no sections at all return identity fields only and cost 0 credits — useful for market-sizing or exploratory passes.
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 nested filters (like funding_detail.funding_rounds) for round-level conditions — don’t confuse them with overview filters funding_detail.funding_overview.* filters apply to a company’s aggregate funding history (total raised, most recent stage, number of rounds). funding_detail.funding_rounds is a nested filter whose sub-fields (round, date, amount_usd, investors.uuid, investors.lead_investor) apply jointly to a single funding round — not across the company’s whole history. If you need “raised a Series B of at least $10M led by a specific investor,” use the nested funding_detail.funding_rounds filter, not a combination of overview filters, since overview filters can’t guarantee those conditions co-occur in the same round.
Set sort_by and sort_order explicitly for reproducible lists The default sort is relevance, which can shift between calls as the underlying index updates. For lists you’ll re-run periodically (e.g. a weekly prospecting pull) or need to diff over time, sort by a stable field like founded_year, total_funding, or revenue_estimate with an explicit sort_order so the ordering — and therefore your offset-based pagination — stays consistent. Paginate with offset and limit rather than requesting the maximum every time limit maxes out at 500 per request. For segments larger than 500 companies, paginate using offset in increments of your limit rather than assuming everything fits in one call. Combine this with a stable sort_by (see above) so pages don’t overlap or skip companies as the dataset changes between calls.
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.