Docs
OverviewGuidesZero & MCPAPI referenceChangelog
Research

List Research Batches

The workspace's research batches with their progress, newest first.

API key access

Needs the leads:read scope with an API key (ro_pat_...). A signed-in session uses the caller's role.
GET/api/v1/research/batches

Authorization

AuthorizationBearer <token>

Access token from /api/v1/auth/login, or an API key (ro_pat_..., RO-176) from /api/v1/workspaces/current/api-keys: the key implies its workspace and needs the route's scope. MCP connectors (/api/v1/mcp only) may use an OAuth access token (ro_oat_..., RO-284).

In: header

Query Parameters

status?ResearchBatchStatus

Only this status

Value in"queued" | "running" | "paused" | "succeeded" | "failed" | "cancelled"
limit?integer

Default 20

Formatint64
Range1 <= value <= 100

Header Parameters

X-Workspace-Id?string | null

Id of the workspace to act on (must be a member).

Response Body

curl -X GET "http://localhost:8000/api/v1/research/batches?status=queued&limit=1" \  -H "X-Workspace-Id: string"
{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
      "status": "queued",
      "source": "leads",
      "discovery_run_id": "d6b8715e-5f92-4be4-80e6-91de3492f66a",
      "requested_by_id": "e5a2565f-0ccc-4e3e-ace9-5e0c44253010",
      "icp": "string",
      "progress": {
        "total": 0,
        "pending": 0,
        "running": 0,
        "done": 0,
        "failed": 0,
        "skipped": 0
      },
      "llm_calls": 0,
      "max_llm_calls": 0,
      "search_calls": 0,
      "max_search_calls": 0,
      "paused_reason": "string",
      "resume_at": "2019-08-24T14:15:22Z",
      "error": "string",
      "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

List Research Batch Items

A batch's items in queue order, with each result's id and its quality report.

Run Research

Research the lead and its company now; store the result and add a `research_completed` event to the timeline. Without an `icp` in the body, fit is scored against the workspace ICP from `/workspaces/current/profile` (generic B2B fit if that is empty too). 404 for a missing lead, 422 when no source could be gathered, 502 when the model call fails. With `RESEARCH_ASYNC=true` (off by default) the lead is checked (404), the research is queued as a background job and the response is 202 with the job; poll `GET /leads/{id}/research/jobs/{job_id}` and read the result with `/research/latest`. A repeated request while that job is queued or running returns it.