---
title: "Get search run status and matches"
method: GET
path: "/api/v1/searches"
---

# Get search run status and matches

`GET /api/v1/searches`

## Request

- Base URL: `https://jobherder.com`
- URL: `https://jobherder.com/api/v1/searches`
- Auth: HTTP bearer

## Query parameters

- `run_id` string, required

## Response `200`

Run status; matches present on terminal success

- object
  - `run` object
    - `run_id` string
    - `status` string
    - `plan` 'one_off' | 'agent_quick'
    - `deliveries` integer
    - `target_jobs` integer
    - `started_at` string, date-time
    - `finished_at` string, date-time, nullable
    - `terminal` boolean
    - `progress` number
    - `stage` string
    - `user_message` string
  - `matches` object[]: Present on terminal success
    - `title` string
    - `company` string
    - `url` string, uri
    - `score` number
    - `rank` integer
    - `source` string
    - `match_reason` string, nullable: Why the candidate fits this role, from scoring. Null for runs completed before 31 Jul 2026.
    - `delivered_at` string, date-time
    - `documents` object, nullable: The tailored documents for this specific role, as markdown. The same documents are emailed as PDFs. Null on runs completed before 1 Aug 2026.
      - `cv_markdown` string, nullable: The CV rewritten for this role
      - `cover_letter_markdown` string, nullable: A cover letter written for this role
  - `documents_note` string

---

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