Research Jobs API endpoint
Submits bounded research over the selected web, arXiv paper, and developer-document sources. Repeated owner-scoped idempotency requests return the original job.
/research/jobsSubmit a durable, owner-scoped research job across public sources. Repeating the same request with the same idempotency key returns the original job. New submissions use current defaults and source/model snapshots; replays use the already accepted job.
Body parameters:
idempotency_key (required): 16–128 characters.query (required): 1–4,000 characters.scope: web, papers, developer, or mixed; defaults to web.output_format: report or json; defaults to report.schema: required only for json; root must be an object. Strict object schemas require every property and additionalProperties:false. References and unsupported keywords are rejected. Maximum 24 KiB, depth 8, and 80 properties.seed_urls, include_domains, exclude_domains: optional web inputs; accepted only for web or mixed. Seed and redirect checks still enforce safe public HTTP(S) targets.sources: optional source IDs from the research source catalog.limits.rounds: 1–5, default 3.limits.searches: 1–20, default 8.limits.sources: 1–50, default 20.limits.timeout_seconds: 30–600, default 180. Counts from the moment work on the job starts, not from submission.limits.input_tokens: 1,000–100,000, default 60,000.limits.output_tokens: 256–16,000, default 8,000.limits.browser_renders: must be 0.limits.max_credits (required): 1–10,000 maximum credits for the job.A successful new submission returns HTTP 202 with job_id, state, signed-owner status/results URLs, and deadline_at. deadline_at is the latest possible finish time (up to 30 minutes of queue wait plus limits.timeout_seconds); it moves earlier in the status response once the job starts. A job that waits more than 30 minutes without starting fails with a timeout error ("job was not started within the 30-minute queue limit") and is not charged. The submission itself has no per-request work charge; the accepted job holds its bounded work budget.
Job state values: queued, running, cancelling, succeeded, failed, cancelled.
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| x-api-key (header) | string | Yes | API key | ||
| request (body) | object | Yes | Research request; `scope` is `web`, `papers`, `developer`, or `mixed`; `output_format` is `report` or `json`. |
curl -X POST "https://api.crawlora.net/api/v1/research/jobs" \
-H "x-api-key: $CRAWLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"exclude_domains":["string"],"idempotency_key":"0123456789abcdef","include_domains":["string"],"limits":{"browser_renders":0,"input_tokens":60000,"max_credits":1,"output_tokens":8000,"rounds":3,"searches":8,"sources":20,"timeout_seconds":180},"output_format":"report","query":"How do recent studies measure retrieval quality?","schema":{},"scope":"mixed","seed_urls":["string"],"sources":["string"]}'{
"exclude_domains": [
"string"
],
"idempotency_key": "0123456789abcdef",
"include_domains": [
"string"
],
"limits": {
"browser_renders": 0,
"input_tokens": 60000,
"max_credits": 1,
"output_tokens": 8000,
"rounds": 3,
"searches": 8,
"sources": 20,
"timeout_seconds": 180
},
"output_format": "report",
"query": "How do recent studies measure retrieval quality?",
"schema": {},
"scope": "mixed",
"seed_urls": [
"string"
],
"sources": [
"string"
]
}{
"code": 202,
"msg": "Accepted",
"data": {
"job_id": "job-123",
"state": "queued",
"replayed": false,
"status_url": "/api/v1/research/jobs/job-123",
"results_url": "/api/v1/research/jobs/job-123/results",
"deadline_at": "2026-10-09T12:00:00Z"
}
}Request schema
#/definitions/researchjobs.researchStartRequestDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| exclude_domains | array | No | ||||
| idempotency_key | string | Yes | 0123456789abcdef | |||
| include_domains | array | No | ||||
| limits | researchjobs.researchLimitsDoc | Yes | ||||
| limits.browser_renders | integer | No | 0 | 0 | ||
| limits.input_tokens | integer | No | min 1000, max 100000 | 60000 | ||
| limits.max_credits | integer | Yes | min 1, max 10000 | |||
| limits.output_tokens | integer | No | min 256, max 16000 | 8000 | ||
| limits.rounds | integer | No | min 1, max 5 | 3 | ||
| limits.searches | integer | No | min 1, max 20 | 8 | ||
| limits.sources | integer | No | min 1, max 50 | 20 | ||
| limits.timeout_seconds | integer | No | min 30, max 600 | 180 | ||
| output_format | string | No | report, json | report | ||
| query | string | Yes | How do recent studies measure retrieval quality? | |||
| schema | object | No | ||||
| scope | string | No | web, papers, developer, mixed | mixed | ||
| seed_urls | array | No | ||||
| sources | array | No |
Response schema
No response schema
| Status | Description | Schema |
|---|---|---|
| 400 | Invalid request | #/definitions/app.Response |
| 401 | Authentication required | #/definitions/app.Response |
| 503 | Research service or billing admission 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/research/jobs" \
-H "x-api-key: $CRAWLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"exclude_domains":["string"],"idempotency_key":"0123456789abcdef","include_domains":["string"],"limits":{"browser_renders":0,"input_tokens":60000,"max_credits":1,"output_tokens":8000,"rounds":3,"searches":8,"sources":20,"timeout_seconds":180},"output_format":"report","query":"How do recent studies measure retrieval quality?","schema":{},"scope":"mixed","seed_urls":["string"],"sources":["string"]}'