Research Jobs API endpoint
Reads a page of events for one of the caller's research jobs, by `job_id`. `limit` is 1 to 100 (default 50); pass `next_cursor` back as `cursor` to continue, with `has_more` showing whether more remain. Each event has `sequence`, `type` (such as `source_fetched` or `round_completed`), `timestamp`, `message` and `source_id`.
/research/jobs/{job_id}/eventsReads a signed, owner-bound page of events for a research job.
Path parameters:
job_id (required): the ID returned by research-start.Example request path: GET /api/v1/research/jobs/job-123/events.
Query parameters:
cursor (optional): signed continuation cursor from the prior response.limit (optional): 1–100 events; defaults to 50.Event type values: submitted, started, search_completed, source_fetched, round_completed, cancellation_requested, completed, failed, cancelled.
Failure reason values: invalid_url, unsupported_content_type, blocked, not_found, rate_limited, timeout, upstream_error, internal_error, out_of_scope, robots_disallowed, duplicate, limit_reached, unsupported_filter, unknown_source, idempotency_conflict, invalid_cursor, result_expired, full_text_unavailable, budget_exhausted.
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key | ||
| job_id (path) | string | Yes | Research job ID | job-123 | |
| cursor | string | No | Signed event cursor | ||
| limit | integer | No | Page size from 1 through 100; default 50 Minimum: 1. Maximum: 100. |
curl -X GET "https://api.crawlora.net/api/v1/research/jobs/job-123/events?limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"job_id": "job-123",
"items": [
{
"sequence": 1,
"type": "started",
"timestamp": "2026-10-09T11:00:05Z",
"message": "research worker started"
}
],
"next_cursor": "signed-cursor",
"has_more": false
}
}Request schema
No body schema
Response schema
#/definitions/researchjobs.researchEventsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | ||||
| data | retrievaltypes.JobEventsResponse | No | ||||
| data.has_more | boolean | No | ||||
| data.items | array | No | ||||
| data.items[].message | string | No | ||||
| data.items[].sequence | integer | No | ||||
| data.items[].source_id | string | No | ||||
| data.items[].timestamp | string | No | ||||
| data.items[].type | retrievaltypes.JobEventType | No | submitted, started, search_completed, source_fetched, round_completed, cancellation_requested, completed, failed, cancelled | |||
| data.job_id | string | No | ||||
| data.next_cursor | string | No | ||||
| msg | string | No |
| Status | Description | Schema |
|---|---|---|
| 400 | Invalid page request or cursor | #/definitions/app.Response |
| 401 | Authentication required | #/definitions/app.Response |
| 404 | Research job not found | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/research/jobs/job-123/events?limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"