Docs
OverviewGuidesZero & MCPAPI referenceChangelog
Research

List Research Batch Items

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

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/{batch_id}/items

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

Path Parameters

batch_idstring
Formatuuid

Query Parameters

status?ResearchBatchItemStatus

Only this status

Value in"pending" | "running" | "done" | "failed" | "skipped"
limit?integer

Default 50

Formatint64
Range1 <= value <= 200
cursor?string

next_cursor of the previous page

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/497f6eca-6276-4993-bfeb-53cbbbba6f08/items?status=pending&limit=1&cursor=string" \  -H "X-Workspace-Id: string"
{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
      "lead_id": "9bddab70-98e6-43a9-8f32-c9788b9de0c0",
      "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
      "lead_name": "string",
      "company_name": "string",
      "status": "pending",
      "lead_research_id": "55788760-6a6f-41ae-97c1-8966d8034ca4",
      "company_research_id": "b7a83128-0265-4172-be6e-ef6fedd1070b",
      "error": "string",
      "quality": {
        "property1": null,
        "property2": null
      },
      "attempts": 0,
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Get Research Job

A research run queued with `RESEARCH_ASYNC=true` (RO-077): its state, the last error and, once it succeeded, the stored result's id. 404 if the lead is missing or the job is not this lead's research.

List Research Batches

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