---
title: "Start a search"
method: POST
path: "/v1/searches"
tags: ["Searches"]
---

# Start a search

`POST /v1/searches`

## Request

- Base URL: `https://api.nvoke.run`
- URL: `https://api.nvoke.run/v1/searches`
- Auth: HTTP bearer

Queues a search and returns it at once with status `queued`. Our servers find the companies, read their websites and check every address. Poll `GET /v1/searches/{id}` until the status is `done`, `failed` or `canceled`. `limit` caps the companies looked at (default 100, at most 1,000). Kind `domains` takes a list you already have in `params.items`: domains, URLs, email addresses (for their domain) or company names, up to 1,000. Domains are read as given; each name is looked up on the web and its website kept. Its `limit` defaults to the length of the list. Kind `icp` takes who you sell to in plain words (`params.description`, optionally `product`, `countries` and `locations`): nvoke plans the queries, reads agency directories and list pages, keeps the companies that fit and reports what it does in `stage` and `stageNote`. Shared inboxes (info@, sales@) are found but not checked: they reach no person, so they stay hidden and free. Send `checkInboxes: true` to check them too, or switch it on later with `PATCH /v1/searches/{id}`.

## Request body

- union
  - object
    - `kind` 'local', required
    - `params` object, required
      - `niche` string, required
      - `location` string, required
    - `limit` integer
    - `checkInboxes` boolean
  - object
    - `kind` 'web', required
    - `params` object, required
      - `keyword` string, required
      - `country` string
    - `limit` integer
    - `checkInboxes` boolean
  - object
    - `kind` 'launches', required
    - `params` object, required
      - `keyword` string
      - `days` integer
      - `sources` string[]
    - `limit` integer
    - `checkInboxes` boolean
  - object
    - `kind` 'domains', required
    - `params` object, required
      - `items` string[], required
      - `country` string
    - `limit` integer
    - `checkInboxes` boolean
  - object
    - `kind` 'icp', required
    - `params` object, required
      - `description` string, required
      - `product` string
      - `countries` string[]
      - `locations` string[]
    - `limit` integer
    - `checkInboxes` boolean

## Response `201`

OK

- union
  - object
    - `id` string, uuid, required
    - `limit` integer, required
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'canceled', required
    - `error` string, nullable, required
    - `companiesFound` integer, required
    - `companiesCrawled` integer, required
    - `emailsFound` integer, required
    - `emailsValid` integer, required
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `stage` string, nullable
    - `stageNote` string, nullable
    - `ongoing` boolean, nullable
    - `checkInboxes` boolean, nullable
    - `inboxesSkipped` integer, nullable
    - `inboxesPending` integer, nullable
    - `kind` 'local', required
    - `params` object, required
      - `niche` string, required
      - `location` string, required
    - `runs` object[]
      - `params` object, required
        - `niche` string, required
        - `location` string, required
      - `limit` integer, required
      - `foundBefore` integer, required
      - `createdAt` string, date-time, required
      - `trigger` 'escalate' | 'ongoing'
  - object
    - `id` string, uuid, required
    - `limit` integer, required
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'canceled', required
    - `error` string, nullable, required
    - `companiesFound` integer, required
    - `companiesCrawled` integer, required
    - `emailsFound` integer, required
    - `emailsValid` integer, required
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `stage` string, nullable
    - `stageNote` string, nullable
    - `ongoing` boolean, nullable
    - `checkInboxes` boolean, nullable
    - `inboxesSkipped` integer, nullable
    - `inboxesPending` integer, nullable
    - `kind` 'web', required
    - `params` object, required
      - `keyword` string, required
      - `country` unknown
    - `runs` object[]
      - `params` object, required
        - `keyword` string, required
        - `country` unknown
      - `limit` integer, required
      - `foundBefore` integer, required
      - `createdAt` string, date-time, required
      - `trigger` 'escalate' | 'ongoing'
  - object
    - `id` string, uuid, required
    - `limit` integer, required
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'canceled', required
    - `error` string, nullable, required
    - `companiesFound` integer, required
    - `companiesCrawled` integer, required
    - `emailsFound` integer, required
    - `emailsValid` integer, required
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `stage` string, nullable
    - `stageNote` string, nullable
    - `ongoing` boolean, nullable
    - `checkInboxes` boolean, nullable
    - `inboxesSkipped` integer, nullable
    - `inboxesPending` integer, nullable
    - `kind` 'launches', required
    - `params` object, required
      - `keyword` string
      - `days` integer, required
      - `sources` string[]
    - `runs` object[]
      - `params` object, required
        - `keyword` string
        - `days` integer, required
        - `sources` string[]
      - `limit` integer, required
      - `foundBefore` integer, required
      - `createdAt` string, date-time, required
      - `trigger` 'escalate' | 'ongoing'
  - object
    - `id` string, uuid, required
    - `limit` integer, required
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'canceled', required
    - `error` string, nullable, required
    - `companiesFound` integer, required
    - `companiesCrawled` integer, required
    - `emailsFound` integer, required
    - `emailsValid` integer, required
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `stage` string, nullable
    - `stageNote` string, nullable
    - `ongoing` boolean, nullable
    - `checkInboxes` boolean, nullable
    - `inboxesSkipped` integer, nullable
    - `inboxesPending` integer, nullable
    - `kind` 'domains', required
    - `params` object, required
      - `items` unknown, required
      - `country` unknown
    - `runs` object[]
      - `params` object, required
        - `items` unknown, required
        - `country` unknown
      - `limit` integer, required
      - `foundBefore` integer, required
      - `createdAt` string, date-time, required
      - `trigger` 'escalate' | 'ongoing'
  - object
    - `id` string, uuid, required
    - `limit` integer, required
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'canceled', required
    - `error` string, nullable, required
    - `companiesFound` integer, required
    - `companiesCrawled` integer, required
    - `emailsFound` integer, required
    - `emailsValid` integer, required
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `stage` string, nullable
    - `stageNote` string, nullable
    - `ongoing` boolean, nullable
    - `checkInboxes` boolean, nullable
    - `inboxesSkipped` integer, nullable
    - `inboxesPending` integer, nullable
    - `kind` 'drop', required
    - `params` object, required
      - `dropId` string, uuid, required
      - `dropName` string, required
      - `keyword` string
      - `sources` string[], required
  - object
    - `id` string, uuid, required
    - `limit` integer, required
    - `status` 'queued' | 'running' | 'done' | 'failed' | 'canceled', required
    - `error` string, nullable, required
    - `companiesFound` integer, required
    - `companiesCrawled` integer, required
    - `emailsFound` integer, required
    - `emailsValid` integer, required
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `stage` string, nullable
    - `stageNote` string, nullable
    - `ongoing` boolean, nullable
    - `checkInboxes` boolean, nullable
    - `inboxesSkipped` integer, nullable
    - `inboxesPending` integer, nullable
    - `kind` 'icp', required
    - `params` object, required
      - `description` string, required
      - `product` string
      - `countries` unknown[]
        - unknown
      - `locations` string[]
    - `runs` object[]
      - `params` object, required
        - `description` string, required
        - `product` string
        - `countries` unknown[]
          - unknown
        - `locations` string[]
      - `limit` integer, required
      - `foundBefore` integer, required
      - `createdAt` string, date-time, required
      - `trigger` 'escalate' | 'ongoing'

## Other responses

- `4XX`: `unauthorized`: No valid token. Send `Authorization: Bearer <key>`. `invalid_request`: The body or query failed validation. `details` lists the problems. `quota_exceeded`: This month’s verified emails are used up. A human upgrades at `billingUrl`, sent with this error and by `GET /v1/me`. `source_unavailable`: Web search is paused on our side. Local and launch searches still work.

## Changes

- **2026-10-20** `f7cfd26111a8`: 1 breaking, 1 info
  - removed `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5` from the request body `oneOf` list
  - added `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5` to the request body `oneOf` list

[Operation history](https://skmtc.dev/nvoke/apis/nvoke-api/changes/v1/searches/post.md)

---

[API](https://skmtc.dev/nvoke/apis/nvoke-api.md) · [All operations](https://skmtc.dev/nvoke/apis/nvoke-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nvoke/apis/nvoke-api/revisions/f7cfd26111a8?raw)