---
title: "Create a resumable lead-search job from one brief"
method: POST
path: "/api/v1/searches"
---

# Create a resumable lead-search job from one brief

`POST /api/v1/searches`

## Request

- Base URL: `https://crawdar.com`
- URL: `https://crawdar.com/api/v1/searches`
- Auth: one of:
  - none
  - API key in header `x-api-key`

At most ten queued or running jobs per account, with two concurrent executions. Poll the same queued job and honor Retry-After. Do not create replacement jobs while work is queued.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `brief` string, required: One natural-language lead brief. Geography and public-evidence requirements may be included.
    - `target` string
    - `geography` string
    - `qualifier` string
    - `fields` string[]
    - `sources` string[]
    - `limit` integer
  - object
    - `brief` string: One natural-language lead brief. Geography and public-evidence requirements may be included.
    - `target` string, required
    - `geography` string, required
    - `qualifier` string
    - `fields` string[]
    - `sources` string[]
    - `limit` integer

## Response `201`

Search job completed from cache

- SearchJobEnvelope
  - `id` string, uuid, required
  - `status` 'queued' | 'running' | 'completed' | 'failed' | 'canceled', required
  - `jobToken` string: Shown once. Send it in x-job-token for subsequent requests.
  - `statusUrl` string, uri, required
  - `exportUrl` string, uri, required
  - `retryUrl` string, uri, required
  - `cancelUrl` string, uri, required
  - `progress` object
  - `expiresInSeconds` integer, required
  - `cacheHit` boolean
  - `resultCount` integer

## Other responses

- `202`: Search job accepted and running asynchronously
- `400`: Invalid lead brief
- `429`: Free usage or provider capacity reached

---

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