Research API endpoint
Return one-hop Europe PMC citation edges, canonical seed IDs, source provenance and a frozen owner-bound cursor. Modes are references and citers; intent is unsupported. Partial results explicitly report indexed-source and candidate-window limits.
/research/papers/relatedReturn a bounded one-hop Europe PMC citation neighborhood with canonical nodes, seed mapping and source provenance. Requires x-api-key. This endpoint returns indexed citation evidence, not title similarity or a universal scholarly graph.
Request body:
seed_ids: required for a new graph, 1–10 unique identifiers of up to 256 characters. Use PMID, PMCID, DOI or registered canonical IDs with a supported Europe PMC alias. An arXiv record needs a known Europe PMC-resolvable alias; otherwise graph coverage is unavailable.mode: required for a new graph; exactly references (seed cites returned paper) or citers (returned paper cites seed).limit: optional page size 1–50, default 10.cursor: optional signed continuation cursor. Supply only cursor and optional limit when continuing.intent: unsupported; supplying it returns 400 before upstream IO.Response behavior:
seeds maps canonical seed IDs to primary source identifiers, with status exactly ok or failed for the validated list outcome. items contains normalized paper nodes. relations contains directed from_id/to_id, source_id, exact graph source_url and retrieval timestamp. An initial request captures up to 50 indexed neighbors per successful unique seed, with a combined 200-node window. Alias-equivalent seeds are queried/charged once. Shared neighbors retain edges from every successful seed. Each frozen page includes its nodes' seed relations. Source counts, unresolved/non-supported reference rows, deadline and candidate caps can make partial=true; warnings state the limitation. Citation lists can differ from the full bibliography and commercial citation databases.
Snapshots last 30 minutes. Signed cursors bind owner, operation, normalized query and source revision. Continuation performs no source queries, returns zero new usage/cost, and retains the original coverage/provenance. Invalid/cross-owner cursors fail; expired or removed snapshots return 410.
Billing: 3 credits per successful unique seed whose metadata and graph response were validated and whose graph edges were retained, including genuine zero-neighbor responses. Positive lists that produce no retainable edges are not charged. Metadata resolution is included in this price; failed seed lookups are not charged. Initial static ceiling is 30 credits; dynamic precheck bounds the submitted seed count. Cursor pages cost zero. A partial response charges only successful delivered seed work. All-failed source work returns 503 with no charge; malformed inputs return 400.
Response enum values:
paper.identifiers[].namespace: arxiv, doi, pmid, pmcid.paper.content_level: metadata, abstract, full_text.unavailable_reason: not_indexed, restricted, unsupported_format, not_found.coverage[].status: ok, failed, not_indexed, unsupported.coverage[].failure.reason: 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.warnings[].code: source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, cached_source_stale.Example request:
{"seed_ids":["pmid:17299597"],"mode":"references","limit":1}
Returned europepmc:MED:<id> / europepmc:PMC:<pmcid> primary IDs and public https://europepmc.org/article/MED/<id> / article/PMC/<id> URLs can be reused as paper identifiers. Other Europe PMC source codes are outside this resolver.
| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| paper | 1 | |
| rank | 1 | 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| request (body) | object | Yes | Seed IDs and graph direction, or cursor and optional limit |
curl -X POST "https://api.crawlora.net/api/v1/research/papers/related" \
-H "x-api-key: $CRAWLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cursor":"string","intent":"string","limit":1,"mode":"references","seed_ids":["string"]}'{
"cursor": "string",
"intent": "string",
"limit": 1,
"mode": "references",
"seed_ids": [
"string"
]
}{
"code": 200,
"msg": "OK",
"data": {
"seeds": [
{
"paper_id": "paper:seed-uuid",
"primary_id": "europepmc:MED:17299597",
"status": "ok"
}
],
"items": [
{
"paper": {
"paper_id": "paper:neighbor-uuid",
"primary_id": "europepmc:MED:10781045"
},
"rank": 1
}
],
"relations": [
{
"from_id": "paper:seed-uuid",
"to_id": "paper:neighbor-uuid",
"source_id": "europepmc",
"source_url": "https://www.ebi.ac.uk/europepmc/webservices/rest/MED/17299597/references?format=json&page=1&pageSize=50",
"retrieved_at": "2026-10-10T02:00:00Z"
}
],
"has_more": true,
"next_cursor": "signed-owner-bound-cursor",
"partial": false,
"coverage": [
{
"source_id": "europepmc",
"status": "ok"
}
],
"warnings": [],
"usage": {
"credits_charged": 3,
"settlement_pending": false
}
}
}Request schema
#/definitions/researchpapers.PaperRelatedRequest
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| cursor | string | No | ||||
| intent | string | No | ||||
| limit | integer | No | ||||
| mode | researchpapers.RelatedMode | No | references, citers | |||
| seed_ids | array | No |
Response schema
Inline response schema
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | Code is the HTTP status code or a custom code used to indicate the result of the request @example 200 | |||
| data | researchretrieval.PaperRelatedResponse | No | ||||
| data.coverage | array | No | PaperSourceCoverage record, 10 fields: corpus_revision, failure, indexed_at, retrieved_at, source_id, status. Described under Read a research paper API. | |||
| data.has_more | boolean | No | ||||
| data.items | array | No | PaperHit record, 19 fields: paper, rank, score. Described under Search research papers API. | |||
| data.next_cursor | string | No | ||||
| data.partial | boolean | No | ||||
| data.relations | array | No | ||||
| data.relations[].from_id | string | No | ||||
| data.relations[].retrieved_at | string | No | ||||
| data.relations[].source_id | string | No | ||||
| data.relations[].source_url | string | No | ||||
| data.relations[].to_id | string | No | ||||
| data.seeds | array | No | ||||
| data.seeds[].paper_id | string | No | ||||
| data.seeds[].primary_id | string | No | ||||
| data.seeds[].status | string | No | ok, failed | |||
| 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 Read a research paper API. | |||
| 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 | unknown | No | Msg is the message that describes the result of the request @example "Request successful" |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 401 | Unauthorized | #/definitions/app.Response |
| 402 | Payment Required | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 410 | Gone | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service 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/papers/related" \
-H "x-api-key: $CRAWLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cursor":"string","intent":"string","limit":1,"mode":"references","seed_ids":["string"]}'