meta-paper-relations: paginate a paper's relations
Paginate the full citations / references / related-works list of a paper.
Overview
citations / references / related_works are unbounded arrays (a highly-cited paper can have thousands). meta-search only inlines a truncated few; use this endpoint for the full list. First obtain the paper's unique_id from meta-search or agentic-search, then paginate by relation.
Use cases
- · What does paper X cite (relation=REFERENCES)
- · Which papers cite paper X (relation=CITATIONS)
- · Works related to paper X (relation=RELATED_WORKS)
Not for
- · Use content, not this endpoint, to read source text by doc_id.
- · Use agentic-search for semantic evidence retrieval.
- · Use meta-search for structured paper-list filtering.
Capability boundaries
- · meta-paper-relations queries citations, references, or related works by unique_id, not by doc_id.
- · relation only supports CITATIONS, REFERENCES, and RELATED_WORKS.
- · Highly cited papers may require paginated reads; keep page_size within public limits.
- · Relation items are paper-relation records, not full-text evidence chunks.
Authentication
Use API key Bearer token authentication for all requests. Add this HTTP header:
Authorization: Bearer YOUR_API_TOKEN
Request example
curl -X POST https://api.sciverse.space/meta-paper-relations \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"unique_id":"paper:10.1038/s41586-021-03819-2","relation":"CITATIONS","page":1,"page_size":25}'Request body (JSON)
Pick one relation; CITATIONS (incoming: who cites me) and REFERENCES (outgoing: who I cite) are opposite directions.
| Field | Type | Required | Description |
|---|---|---|---|
| unique_id | string | Required | Target paper unique_id (e.g. paper:10.1038/xxx) from meta-search / agentic-search; do not pass doc_id. |
| relation | string | Required | Relation type: CITATIONS (incoming) / REFERENCES (outgoing) / RELATED_WORKS. |
| page | integer | Optional | Page number. Default 1Range >= 1 |
| page_size | integer | Optional | Items per page. Default 25Range 1-200 |
Response structure
| Field | Type | Description |
|---|---|---|
| items | array<object> | Relation entries, each { id, id_type, title }. |
| total_count | integer | Total number of relations. |
| page | integer | Current page number. |
| page_size | integer | Items per page. |
| total_pages | integer | Total pages. |
| code / message / biz_code | object | Unified success envelope fields. |
Response example
{
"items": [{"id": "10.1080/10400419.2011.571190", "id_type": "doi", "title": "Contesting ... Theory of Creativity"}],
"total_count": 128,
"page": 1,
"page_size": 25,
"total_pages": 6,
"code": "SUCCESS",
"message": "OK",
"biz_code": 0
}Errors
| Code | Message | Description |
|---|---|---|
| 400 | INVALID_ARGUMENT | Invalid params: empty unique_id or bad relation. |
| 403 | FORBIDDEN | No access to the relation field (citations/references/related_works). |
| 404 | NOT_FOUND | No document found for unique_id. |
| 429 | RATE_LIMITED | Rate limited; retry after the window resets. |
| 502 | UPSTREAM_UNAVAILABLE | Upstream metadata-service unavailable. |
See the Errors section for shared error codes.
Parameter bounds
| Limit | Value |
|---|---|
| page | >= 1 |
| page_size | 1-200 (default 25) |
| Default rate limit | 30 req / minute (per user) |
Retry guidance
- · Retry: 502 / 503 / 504
- · Do not retry: 400 / 401 / 403 / 404
- · 429: wait out the rate-limit window
FAQ
Where do I get unique_id?
Usually from a meta-search result after locating the target paper.
What is the difference between CITATIONS and REFERENCES?
CITATIONS means papers that cite the target paper. REFERENCES means papers cited by the target paper.
Can I query relations with doc_id?
No. doc_id is for content reads. The relation endpoint requires unique_id.
Can related works replace semantic search?
No. RELATED_WORKS is a relation signal. Use agentic-search for open-ended semantic evidence retrieval.
Need an API key?
Create one in Console > Tokens.The same API key works for enabled Sciverse, DianShi, and Skills capabilities, with starter quota available according to account permissions.