Research Jobs API endpoint
Returns the complete owner-scoped retained result prefix up to a consistent manifest sequence. Before a valid report or structured result exists, returns `ready=false` with `partial=true` and any retained evidence.
/research/jobs/{job_id}/resultsReturns all retained results through a consistent manifest sequence, bounded to 1 MiB. snapshot_sequence identifies the final manifest sequence included. Search snippets are reported separately from citable evidence. An arXiv abstract is explicitly labeled Abstract; citations also include the exact versioned source URL, document revision, full-content SHA-256, and exact passage.
Path parameters:
job_id (required): the ID returned by research-start.Example request path: GET /api/v1/research/jobs/job-123/results.
result_kind values: evidence_only, report, structured.
source_kind values: web, paper, developer. source_snapshot includes scope (web, papers, developer, or mixed), frozen registry_revision, and each selected source_id, kind (web, paper, or developer), immutable generation_id, and source_revision used for the accepted job.
Claim support_status values: supported, conflicting, unverified. A claim is marked supported only when its full text exactly quotes a retained passage; matching citation IDs alone is not sufficient.
ready is true only when a validated requested report or structured output exists. While work is pending or synthesis cannot be retained, the endpoint returns HTTP 200 with ready:false, partial:true, and all bounded search/evidence items currently retained. report_markdown and structured_data are absent from an evidence_only result.
The response may include up to 20 typed searches, 200 evidence items, 200 claims, and 4,096 characters per passage. JSON results follow the accepted schema; references are not fetched remotely.
Warning code values: source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, cached_source_stale.
Source coverage status values: ok, failed, not_indexed, unsupported.
Shared response schema enum values: blocked, budget_exhausted, duplicate, full_text_unavailable, idempotency_conflict, internal_error, invalid_cursor, invalid_url, limit_reached, not_found, out_of_scope, rate_limited, result_expired, robots_disallowed, timeout, unknown_source, unsupported_content_type, unsupported_filter, upstream_error.
| 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 GET "https://api.crawlora.net/api/v1/research/jobs/job-123/results" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"job_id": "job-123",
"source_snapshot": {
"registry_revision": "registry-1",
"scope": "mixed",
"sources": [
{
"source_id": "web",
"kind": "web",
"generation_id": "web-42",
"source_revision": "r17"
}
]
},
"result_kind": "evidence_only",
"ready": false,
"partial": true,
"searches": [
{
"query": "example evidence",
"source_kind": "web",
"source_id": "web",
"hits": [
{
"url": "https://example.org/article",
"title": "Example",
"snippet": "Search summary..."
}
]
}
],
"evidence": [],
"claims": [],
"warnings": [
{
"code": "content_unavailable",
"message": "document could not be retained"
}
],
"usage": {
"search_requests": 1,
"fetch_attempts": 1,
"fetched_urls": 0,
"browser_renders": 0,
"input_tokens": 0,
"output_tokens": 0,
"credits_reserved": 100,
"credits_charged": 3,
"credits_released": 0,
"settlement_pending": true
}
}
}Request schema
No body schema
Response schema
#/definitions/researchjobs.researchResultsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | ||||
| data | researchjobs.ResearchResult | No | ||||
| data.claims | array | No | ||||
| data.claims[].claim_id | string | No | ||||
| data.claims[].evidence_ids | array | No | ||||
| data.claims[].support_status | retrievaltypes.ClaimSupportStatus | No | supported, conflicting, unverified | |||
| data.claims[].text | string | No | ||||
| data.coverage | array | No | ||||
| data.coverage[].corpus_revision | string | No | ||||
| data.coverage[].failure | retrievaltypes.Failure | No | Failure record, 4 fields: message, reason, retry_after_seconds, retryable. Described under Cancel a research job API. | |||
| data.coverage[].indexed_at | string | No | ||||
| data.coverage[].retrieved_at | string | No | ||||
| data.coverage[].source_id | string | No | ||||
| data.coverage[].status | retrievaltypes.CoverageStatus | No | ok, failed, not_indexed, unsupported | |||
| data.evidence | array | No | ||||
| data.evidence[].content_sha256 | string | No | ||||
| data.evidence[].evidence_id | string | No | ||||
| data.evidence[].passage | retrievaltypes.Passage | No | ||||
| data.evidence[].passage.locator | retrievaltypes.PassageLocator | No | ||||
| data.evidence[].passage.locator.anchor | string | No | ||||
| data.evidence[].passage.locator.end_byte | integer | No | ||||
| data.evidence[].passage.locator.end_line | integer | No | ||||
| data.evidence[].passage.locator.heading | string | No | ||||
| data.evidence[].passage.locator.page | integer | No | ||||
| data.evidence[].passage.locator.start_byte | integer | No | ||||
| data.evidence[].passage.locator.start_line | integer | No | ||||
| data.evidence[].passage.passage_id | string | No | ||||
| data.evidence[].passage.score | number | No | ||||
| data.evidence[].passage.text | string | No | ||||
| data.evidence[].retrieved_at | string | No | ||||
| data.evidence[].revision | string | No | ||||
| data.evidence[].source_id | string | No | ||||
| data.evidence[].source_kind | retrievaltypes.SourceKind | No | web, paper, developer | |||
| data.evidence[].title | string | No | ||||
| data.evidence[].url | string | No | ||||
| data.job_id | string | No | ||||
| data.partial | boolean | No | ||||
| data.ready | boolean | No | ||||
| data.report_markdown | string | No | ||||
| data.result_kind | string | No | evidence_only, report, structured | |||
| data.searches | array | No | ||||
| data.searches[].hits | array | No | ||||
| data.searches[].hits[].snippet | string | No | ||||
| data.searches[].hits[].source_id | string | No | ||||
| data.searches[].hits[].title | string | No | ||||
| data.searches[].hits[].url | string | No | ||||
| data.searches[].query | string | No | ||||
| data.searches[].source_id | string | No | ||||
| data.searches[].source_kind | string | No | web, paper, developer | |||
| data.snapshot_sequence | integer | No | ||||
| data.source_snapshot | researchjobs.SourceSnapshot | No | ||||
| data.source_snapshot.registry_revision | string | No | ||||
| data.source_snapshot.scope | string | No | web, papers, developer, mixed | |||
| data.source_snapshot.sources | array | No | ||||
| data.source_snapshot.sources[].generation_id | string | No | ||||
| data.source_snapshot.sources[].kind | string | No | web, paper, developer | |||
| data.source_snapshot.sources[].source_id | string | No | ||||
| data.source_snapshot.sources[].source_revision | string | No | ||||
| data.structured_data | object | No | ||||
| data.usage | retrievaltypes.Usage | No | Usage record, 10 fields: browser_renders, credits_charged, credits_released, credits_reserved, fetch_attempts, fetched_urls, input_tokens, output_tokens, search_requests, settlement_pending. Described under Cancel a research job API. | |||
| 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 GET "https://api.crawlora.net/api/v1/research/jobs/job-123/results" \
-H "x-api-key: $CRAWLORA_API_KEY"