Search companies (billed per row)
search_companiesRead-only
Return companies matching an ICP. BILLABLE — about $0.0067 per returned row (0 rows costs $0) (Tier 0 list price; your account may pay a different rate — call get_balance for your real prices, and read cost.amount_charged in every response for what was actually spent). Run count_companies first. Note that headcount_range is a snapshot taken when the record was indexed and can lag the company's current size; the filter itself is applied at query time.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Data mode. "database" = cached, sub-second, cheaper, free counts, core filters only. "realtime" = live LinkedIn lookup, 5–60s, pricier, supports every filter. "auto" (default) tries database first and only escalates to realtime if a filter you passed is unsupported there — an escalation is reported in the response. Pick "database" explicitly when freshness is not critical and cost matters more than freshness. | |
| limit | No | Alias for limit_by. | |
| offset | No | Alias for offset_by. | |
| compact | No | Default true: return a small per-company summary (including the Generect `id`, which every later step accepts). Set false for the full raw record (~80 fields) — only worth it when you specifically need skills, education or other deep fields. | |
| keywords | No | Free-text keywords across name/description/specialties — realtime only: using it forces the pricier live mode. | |
| limit_by | No | Rows to return this call (1–100, default 25). You are billed per returned row, so this number IS the price of the call. | |
| locations | No | HQ locations — cities, states or countries. | |
| offset_by | No | Rows to skip (pagination). | |
| headcounts | No | Size buckets. Allowed ONLY: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10 000+". | |
| industries | No | Company industries. Must match Generect industry names exactly (e.g. "Software Development"); unknown names are rejected with HTTP 400. | |
| timeout_ms | No | Request timeout in milliseconds. | |
| exclude_ids | No | Exclude companies by LinkedIn id/URN. | |
| technologies | No | Technologies the company uses — realtime only: using it forces the pricier live mode. | |
| company_names | No | Restrict to specific company names — realtime only: using it forces the pricier live mode. | |
| company_types | No | Company types: "Public Company","Privately Held","Non Profit","Government Agency","Educational", … | |
| revenues_range | No | Annual revenue range, single object {min,max} — realtime only: using it forces the pricier live mode. | |
| sub_industries | No | Expand each selected industry to its sub-industries as well (broadens the match). | |
| exclude_domains | No | Exclude companies by domain (e.g. existing customers). | |
| linkedins_links | No | Specific LinkedIn company URLs — realtime only: using it forces the pricier live mode. | |
| headcount_growth | No | Headcount growth in percent — realtime only: using it forces the pricier live mode. | |
| num_of_followers | No | LinkedIn follower buckets: "1-50","51-100","101-1000","1001-5000","5001+" — realtime only: using it forces the pricier live mode. | |
| confirm_spend_usd | No | Explicit approval for an unusually large charge. Calls whose worst case exceeds $5 are refused unless this is set to at least the amount the tool reports. Only set it after the user has agreed to that number. | |
| exclude_locations | No | HQ locations to exclude. | |
| get_max_companies | No | DEPRECATED — accepted but ignored. Always on now: search responses include results_count without asking. | |
| exclude_industries | No | Industries to exclude. | |
| hiring_on_linkedin | No | Only companies actively hiring — realtime only: using it forces the pricier live mode. | |
| fallback_from_leads | No | DEPRECATED — accepted but ignored. Removed. It fabricated lead-derived name aggregates and cost an extra billable query. | |
| department_headcount | No | Department size, e.g. {"name":"engineering","min":10,"max":100} — realtime only: using it forces the pricier live mode. | |
| allow_unlisted_values | No | Escape hatch for the local vocabulary check — see the lead-side field of the same name. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | ||
| cost | No | ||
| mode | No | ||
| note | No | ||
| leads | No | ||
| status | No | ||
| returned | No | ||
| companies | No | ||
| test_mode | No | ||
| spend_guard | No | ||
| results_count | No | ||
| next_page_args | No | ||
| requested_rows | No | ||
| escalation_note | No | ||
| test_mode_notice | No | ||
| vocabulary_warnings | No | ||
| blocked_by_vocabulary | No | ||
| deprecated_params_ignored | No | ||
| escalated_to_realtime_because | No | ||
| api_returned_more_than_requested | No |