Retrieval API endpoint
Requests cancellation of an owned crawl job. This control call does not reserve, charge, or settle credits; retained successful work is reconciled by the job settlement worker.
/web/crawl/{job_id}/canceljob_id must identify a crawl job owned by the authenticated principal. Cancellation is cooperative: the worker stops new external IO, records terminal skips for admitted work that has not produced an outcome, and then transitions the job to cancelled. Existing published results remain readable for 24 hours by default. The cancellation endpoint does not reserve, charge, release, or settle credits; the settlement reconciler accounts for already published successful work. A job ID owned by another principal or belonging to another job kind returns 404.
The returned state is one of queued, running, cancelling, succeeded, failed, or cancelled. completion_reason, when present, is one of frontier_exhausted, completed, page_limit, round_limit, deadline, budget, cancelled, upstream_failure, or internal_failure.
Failure reason values are 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, and budget_exhausted.
Warning code values are source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, and cached_source_stale.
Shared response schema enum values (the owning endpoint emits its own job kind): crawl.
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| job_id (path) | string | Yes | Owned crawl job ID | job-123 |
curl -X POST "https://api.crawlora.net/api/v1/web/crawl/job-123/cancel" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"job_id": "opaque-job-id",
"kind": "crawl",
"state": "cancelling",
"cancel_requested": true,
"partial": true,
"completion_reason": "cancelled",
"created_at": "2026-10-09T04:00:00Z",
"updated_at": "2026-10-09T04:01:00Z",
"deadline_at": "2026-10-09T04:05:00Z",
"progress": {
"discovered": 12,
"discovery_excluded": 2,
"admitted": 10,
"queued": 0,
"in_flight": 0,
"succeeded": 5,
"failed": 0,
"skipped": 5
},
"usage": {
"search_requests": 0,
"fetch_attempts": 6,
"fetched_urls": 5,
"browser_renders": 0,
"input_tokens": 0,
"output_tokens": 0,
"credits_reserved": 100,
"credits_charged": 25,
"credits_released": 75,
"settlement_pending": true
},
"warnings": []
}
}Request schema
No body schema
Response schema
#/definitions/crawlretrieval.crawlStatusEnvelope
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | crawlretrieval.crawlJobStatusDoc | No | ||||
| data.cancel_requested | boolean | No | ||||
| data.completion_reason | string | No | frontier_exhausted, completed, page_limit, round_limit, deadline, budget, cancelled, upstream_failure, internal_failure | |||
| data.created_at | string · date-time | No | ||||
| data.deadline_at | string · date-time | No | ||||
| data.error | crawlretrieval.crawlFailureDoc | No | ||||
| data.error.message | string | No | ||||
| data.error.reason | string | 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 | min 0 | |||
| data.error.retryable | boolean | No | ||||
| data.expires_at | string · date-time | No | ||||
| data.job_id | string | No | ||||
| data.kind | string | No | crawl | |||
| 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.state | string | No | queued, running, cancelling, succeeded, failed, cancelled | |||
| data.updated_at | string · date-time | 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 | string | 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 | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Invalid job ID or query parameter | #/definitions/app.Response |
| 401 | Authentication required | #/definitions/app.Response |
| 404 | Unknown, unowned, or non-crawl job | #/definitions/app.Response |
| 410 | Expired retained crawl data | #/definitions/app.Response |
| 500 | Internal accounting or storage error | #/definitions/app.Response |
| 503 | Required backend unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X POST "https://api.crawlora.net/api/v1/web/crawl/job-123/cancel" \
-H "x-api-key: $CRAWLORA_API_KEY"