Choosing a search endpoint
Vamo exposes more than one way to find developers because they answer different questions. Pick by how much control you want and how long you are willing to wait.
Plan then run, when you want to see the query
POST /v1/searches/plan takes natural language and returns a validated query plan. It is free.
POST /v1/searches/run takes exactly the plan plan returned and executes it. It is billed per developer returned.
The plan is a plain object you can read, edit, and re-run. Change one filter and run it again. That round trip is the refinement loop, and it is the reason planning is free: iterating on a plan is cheaper for both of us than running a bad one.
Reach for this pair when you are building something that shows a user what is about to be searched, or when an agent needs to reason about the query before spending.
Execute, when you just want results
POST /v1/searches/execute takes a search configuration and returns developers in one call, billed per developer returned. It also accepts an optional facets array so a page comes back already enriched, billed in the same call.
Reach for this when you already know your criteria and do not need to inspect a plan first.
Be deliberate about facets on this endpoint:
- Omit it and your account's default enrichment facets are applied and charged. The same request body can therefore cost different amounts on two accounts.
- Send an explicit empty array to suppress enrichment entirely and pay only the base search price.
- Send a list to get exactly those facets and pay for exactly those.
If you are billing your own customers, send the list or the empty array. Do not rely on the account default.
Search jobs, when one page is not enough
POST /v1/searches/jobs submits a long-running search that fills toward a target count across multiple rounds. Poll it with GET /v1/searches/jobs/{id} and ask for another round with POST /v1/searches/jobs/{id}/more.
Reach for this when you want depth rather than the first page, and you can tolerate the wait.
Paging and "show me more"
POST /v1/searches/execute pages with an opaque cursor. To widen a set without repeating anyone, on either endpoint, pass the ids you have already been shown in excludeDeveloperIds. That is how "get me 50 more" works, and it happens before billing, so you are not charged for a repeat you would have discarded.
Deep research is not search
POST /v1/deep-research/jobs is full-depth research on developers you have already identified. It does not find new people. Use it when you have a shortlist and want depth on each name.
Saving a query
POST /v1/saved-searches stores a configuration under a name so you or an agent can re-run it later without rebuilding it.