Hunch

API Reference

Runs & discovery

Start find-accounts discovery runs and inspect any run's mode, status, spec, and result stats.

List runs

GET/runs

Returns runs newest first, paginated.

Query parameters
statusstringoptional

Filter by run status (e.g. running, done, failed).

pageintegeroptional

Page number. Default 1.

per_pageintegeroptional

Max 100. Default 25.

Response
{
  "data": [
    {
      "id": "...",
      "signal_id": "...",
      "name": "New Revenue Leader",
      "mode": "both",
      "status": "done",
      "stats": { "candidates": 18, "accounts": 12, "matched": 3 },
      "timeframe_days": 90,
      "started_at": "2026-07-03T...",
      "finished_at": "2026-07-03T...",
      "created_at": "2026-07-03T..."
    }
  ],
  "pagination": { "total": 30, "page": 1, "per_page": 25, "has_more": true }
}

Find accounts

POST/runs

Starts a discovery run that finds net-new accounts matching a set of signals and firmographic filters. Returns immediately with the run id, work executes in the background.

Body fields
signalsobjectrequired

Signal match rule: { any_of: string[], must_have: string[], exclude: string[] }, all arrays of signal ids. Provide at least one id in any_of or must_have.

namestringoptional

Label for the run.

recencystringoptional

Detection window in days as a string, or "all". Default "90".

geographiesstring[]optional

Restrict to these geographies.

industriesstring[]optional

Restrict to these industries.

employee_minintegeroptional

Minimum headcount.

employee_maxintegeroptional

Maximum headcount.

Discovery consumes paid research resources and requires an active subscription. Without one it returns 402.
Request
curl -X POST https://usehunch.co/api/v1/runs \
  -H "Authorization: Bearer hunch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EMEA expansion",
    "signals": { "any_of": ["SIGNAL_ID"], "must_have": [], "exclude": [] },
    "recency": "90",
    "geographies": ["Europe"],
    "industries": ["SaaS"],
    "employee_min": 200,
    "employee_max": 2000
  }'
202 Accepted
{
  "data": {
    "run_id": "...",
    "status": "running",
    "created_at": "2026-07-03T..."
  }
}

Get a run

GET/runs/:id

Returns the run including its spec (the search rule, for discovery runs) and full stats.

Run modes

  • discovery, find net-new companies showing a signal.
  • monitor, check existing active accounts.
  • both, discovery and monitoring in one run.
PreviousSignalsNext ICPs