Companies

Search Companies

Search for companies using natural language queries. Pass your search text in the "prompt" field (not "query"). Use this to find companies matching specific criteria like industry, location, funding stage, or technology. Examples: "AI startups in San Francisco", "Series B fintech companies", "healthcare companies using Python". By default this searches only companies connected to the caller’s own network; pass scope: "global" to search everyone. Returns matching companies with relevance scores and connection strength. Supports cursor-based pagination for large result sets. Expect this to be slow: complex searches usually take 20-60 seconds. Wait for it to finish rather than retrying or assuming it failed.

post/v2/companies/search

Request

  • Base URL: https://api.village.ai
  • URL: https://api.village.ai/v2/companies/search
  • Auth: HTTP bearer

Request body

promptstring

Natural language search query

limitinteger

Maximum number of results per page

mode'auto' | 'lookup' | 'simple' | 'complex'

Search mode for prompt-only searches: auto (let system decide), lookup (direct match), simple (LLM-powered), or complex (thinking + high-reasoning SQL generation). Structured filters always compile deterministically.

scope'network' | 'global'

Search scope: network (connections first) or global (all companies)

streamboolean

Enable SSE streaming for progressive results

include_counts'global' | 'network' | 'all'

Inline count scopes to compute on the first page only. Use "global", "network", or "all". Ignored when cursor is provided and adds latency.

screening_handoffboolean

Complex searches keep only objective constraints in SQL and return the subjective ones as metadata.screening_criteria for a downstream screening step.

Example request

{
  "prompt": "Find B2B SaaS companies with 50-200 employees in California",
  "filters": {
    "locations": "{\"locations\":[{\"id\":\"6252001\",\"type\":\"country\",\"name\":\"United States\"}]}",
    "locationsNot": "{\"locations\":[{\"id\":\"6252001\",\"type\":\"country\",\"name\":\"United States\"}]}",
    "foundedAfter": 2015,
    "foundedBefore": 2023
  },
  "limit": 25,
  "mode": "auto",
  "list_filter": {
    "company_list_id": 123
  }
}

Response

Search completed successfully

Example response

{
  "pagination": {
    "cursor": "eyJpZCI6IjEyMzQ1In0",
    "has_next_page": true,
    "count": 20
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.