---
title: "Create a new job by changing an existing search brief"
method: POST
path: "/api/v1/searches/{id}/refine"
---

# Create a new job by changing an existing search brief

`POST /api/v1/searches/{id}/refine`

## Request

- Base URL: `https://crawdar.com`
- URL: `https://crawdar.com/api/v1/searches/{id}/refine`
- Auth: API key in header `x-job-token`

## Path parameters

- `id` string, uuid, required

## Request body

- SearchJobRefinement
  - `brief` string
  - `target` string
  - `geography` string
  - `qualifier` string
  - `fields` string[]
  - `limit` integer

## Response `201`

Refined 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`: Refined search job accepted and running asynchronously

---

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