---
title: "Keep a search going, check shared inboxes"
method: PATCH
path: "/v1/searches/{id}"
tags: ["Searches"]
---

# Keep a search going, check shared inboxes

`PATCH /v1/searches/{id}`

## Request

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

Send `ongoing`, `checkInboxes` or both. `checkInboxes` works on every kind: on checks the shared inboxes (info@, sales@) the search left unchecked at companies with no valid personal address (`inboxesSkipped` says how many), low priority after the named people, and shows the valid ones as they settle (`inboxesPending` counts what is still to settle). Only valid ones count against your allowance, like any verified email. A canceled search answers 400 `search_canceled` and a used up allowance 403 `quota_exceeded`. Off stops checking new ones and keeps what was checked. `ongoing` switches daily rounds on or off for a Describe your customer (`icp`) search. An ongoing search runs a fresh round once a day, at the time of day it was created, whenever it is not running: new niches, countries, cities and list pages it has not searched yet, so new leads arrive over days. It pauses while the month’s verified emails are used up and resumes when they renew; `stageNote` says what it does. Off by default; canceling a search switches it off. Every `icp` search also pushes on by itself when it comes up short, up to 3 fresh rounds in 24 hours, ongoing or not. Other kinds answer 400 `ongoing_not_supported`.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `ongoing` boolean
  - `checkInboxes` boolean

## Response `200`

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. `not_found`: No such search, key or webhook on this account. `ongoing_not_supported`: Only Describe your customer (`icp`) searches can be ongoing. `search_canceled`: The search was canceled, so it checks nothing more. Search again into it first. `quota_exceeded`: This month’s verified emails are used up. A human upgrades at `billingUrl`, sent with this error and by `GET /v1/me`.

---

[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)