Research Jobs API endpoint
Requests cancellation of the caller's own research job, given by `job_id`. Returns the job's current state (such as `cancelling`), `cancel_requested`, `partial`, progress counts, research progress and usage. Results already retained stay readable and are marked partial where appropriate.
/research/jobs/{job_id}/cancelRequests cancellation of the authenticated owner’s research job. The handler verifies that the job is a research job before changing its state. Already retained results remain readable and are returned as partial when appropriate.
Path parameters:
job_id (required): the ID returned by research-start.Example request path: POST /api/v1/research/jobs/job-123/cancel.
Job state values: queued, running, cancelling, succeeded, failed, cancelled.
Shared response schema enum values (the owning endpoint emits its own job kind): blocked, budget, budget_exhausted, cached_source_stale, completed, content_unavailable, crawl, deadline, discovery_truncated, duplicate, frontier_exhausted, full_text_unavailable, idempotency_conflict, imprecise_date_excluded, ingestion, internal_error, internal_failure, invalid_cursor, invalid_url, limit_reached, not_found, out_of_scope, page_limit, ranking_window_limit, rate_limited, research, result_expired, robots_disallowed, round_limit, source_failed, source_not_indexed, timeout, unknown_source, unsupported_content_type, unsupported_filter, upstream_error, upstream_failure.
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key | ||
| job_id (path) | string | Yes | Research job ID | job-123 |
curl -X POST "https://api.crawlora.net/api/v1/research/jobs/job-123/cancel" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"job_id": "job-123",
"kind": "research",
"state": "cancelling",
"cancel_requested": true,
"partial": true,
"created_at": "2026-10-09T11:00:00Z",
"updated_at": "2026-10-09T11:01:00Z",
"deadline_at": "2026-10-09T11:03:00Z",
"usage": {
"search_requests": 1,
"fetch_attempts": 0,
"fetched_urls": 0,
"browser_renders": 0,
"input_tokens": 0,
"output_tokens": 0,
"credits_reserved": 100,
"credits_charged": 3,
"credits_released": 0,
"settlement_pending": true
},
"warnings": []
}
}Request schema
No body schema
Response schema
#/definitions/researchjobs.researchStatusResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | ||||
| data | retrievaltypes.JobStatus | No | ||||
| data.cancel_requested | boolean | No | ||||
| data.completion_reason | retrievaltypes.CompletionReason | No | frontier_exhausted, completed, page_limit, round_limit, deadline, budget, cancelled, upstream_failure, internal_failure | |||
| data.created_at | string | No | ||||
| data.deadline_at | string | No | ||||
| data.error | retrievaltypes.Failure | No | ||||
| data.error.message | string | No | ||||
| data.error.reason | retrievaltypes.FailureReason | No | 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 | |||
| data.error.retry_after_seconds | integer | No | ||||
| data.error.retryable | boolean | No | ||||
| data.expires_at | string | No | ||||
| data.job_id | string | No | ||||
| data.kind | retrievaltypes.JobKind | No | crawl, research, ingestion | |||
| data.partial | boolean | No | ||||
| data.progress | retrievaltypes.JobProgress | No | ||||
| data.progress.admitted | integer | No | ||||
| data.progress.discovered | integer | No | ||||
| data.progress.discovery_excluded | integer | No | ||||
| data.progress.failed | integer | No | ||||
| data.progress.in_flight | integer | No | ||||
| data.progress.queued | integer | No | ||||
| data.progress.skipped | integer | No | ||||
| data.progress.succeeded | integer | No | ||||
| data.research | retrievaltypes.ResearchProgress | No | ||||
| data.research.max_rounds | integer | No | ||||
| data.research.questions_answered | integer | No | ||||
| data.research.questions_total | integer | No | ||||
| data.research.round | integer | No | ||||
| data.research.searches_completed | integer | No | ||||
| data.research.sources_read | integer | No | ||||
| data.state | retrievaltypes.JobState | No | queued, running, cancelling, succeeded, failed, cancelled | |||
| data.updated_at | string | No | ||||
| data.usage | retrievaltypes.Usage | No | ||||
| data.usage.browser_renders | integer | No | ||||
| data.usage.credits_charged | integer | No | ||||
| data.usage.credits_released | integer | No | ||||
| data.usage.credits_reserved | integer | No | ||||
| data.usage.fetch_attempts | integer | No | ||||
| data.usage.fetched_urls | integer | No | ||||
| data.usage.input_tokens | integer | No | ||||
| data.usage.output_tokens | integer | No | ||||
| data.usage.search_requests | integer | No | ||||
| data.usage.settlement_pending | boolean | No | ||||
| data.warnings | array | No | ||||
| data.warnings[].code | retrievaltypes.WarningCode | No | source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, cached_source_stale | |||
| data.warnings[].message | string | No | ||||
| data.warnings[].source_id | string | No | ||||
| msg | string | No |
| Status | Description | Schema |
|---|---|---|
| 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 POST "https://api.crawlora.net/api/v1/research/jobs/job-123/cancel" \
-H "x-api-key: $CRAWLORA_API_KEY"