Searches

Answer a research question over the corpus, with citations and the ranked papers behind the answer.

When to use

You have a question and do not know which papers matter yet
You want a synthesized answer plus a screenable paper set
You need an exportable result set (CSV, XLSX, BibTeX, RIS)

When not to use

The caller already knows which PDFs matter → chats
You want the ideas rather than the papers → topics
You only need metadata for a known DOI → papers

Endpoints

Method	Path	Scope	Credits	Description
POST	`/v1/searches`	`search:write`	5 / 15 / 60 by depth	Create a search
GET	`/v1/searches/{id}`	`search:read`	0	Retrieve, incl. status
GET	`/v1/searches`	`search:read`	0	List searches
POST	`/v1/searches/{id}/cancel`	`search:write`	0	Cancel a running search
GET	`/v1/searches/{id}/results`	`search:read`	0	Paginated matched papers
POST	`/v1/searches/{id}/export`	`search:read`	0	Export to a File

This endpoint is asynchronous

Creation returns 202 with status: queued. Poll, use a webhook, or call .wait().

The search object

json

{
  "object": "search",
  "id": "srch_9dm2pq4x1a",
  "status": "succeeded",
  "depth": "standard",
  "query": "How does climate change affect biodiversity?",
  "filters": {
    "year_from": 2015,
    "year_to": null,
    "open_access": true,
    "publication_type": ["journal_article"],
    "venue": []
  },
  "answer": {
    "object": "answer",
    "text": "Warming interacts with habitat fragmentation to accelerate local extinctions [1] …",
    "citations": [ { "index": 1, "quote": "…", "source": {}, "locations": [] } ],
    "unsourced_claim_count": 0
  },
  "paper_count": 20,
  "credits_cost": 5,
  "metadata": { "tenant": "acme-labs" },
  "created_at": "2026-08-11T09:14:22Z",
  "completed_at": "2026-08-11T09:14:29Z",
  "error": null
}

Fields

Field	Type	Description
`id`	string	`srch_`-prefixed identifier
`status`	enum	`queued`, `running`, `succeeded`, `failed`, `canceled`. See job
`depth`	enum	The quality tier the search ran at. See depth
`query`	string	The question as sent, echoed verbatim
`filters`	object	The filters as applied, with unset keys returned as `null` or `[]`
`answer`	object	An [[answer	Answer]]. `null` until `status` is `succeeded`
`answer.text`	string	The synthesis, carrying `[n]` markers keyed to `citations[].index`
`answer.citations`	array	Citation objects, one per marker
`answer.unsourced_claim_count`	integer	Sentences the model could not ground. Surface this
`paper_count`	integer	Papers considered, ≤ `max_papers` and clamped by depth
`credits_cost`	integer	Credits actually charged. `0` while queued
`metadata`	object	Your own key/values, echoed back unchanged
`completed_at`	string	RFC 3339, `null` until terminal
`error`	object	`type`, `code`, `message`. `null` unless `status` is `failed`

Parameters

Parameter	Type	Required	Description
`query`	string	yes	The research question, in natural language
`depth`	enum	no	`standard` (default), `high_quality`, `deep_review`. See depth
`max_papers`	integer	no	Papers considered. Clamped by depth: 20 / 50 / 200
`filters.year_from` / `year_to`	integer	no	Publication window
`filters.open_access`	boolean	no	Restrict to open access
`filters.publication_type`	enum[]	no
`filters.venue`	string[]	no
`answer_format`	enum	no	`bulleted`, `paragraph`
`language`	string	no	Output language, BCP-47. 24 supported; see chats
`metadata`	object	no	Your own key/values, echoed back

Create a search

curl https://api.scispace.com/v1/searches \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --fail-with-body \
  -d '{
    "query": "How does climate change affect biodiversity?",
    "depth": "standard",
    "max_papers": 20,
    "filters": { "year_from": 2015, "open_access": true }
  }'

The create call returns 202 with status: queued. After it settles, the same object carries the answer — one citation shown here in full, the rest elided:

json

{
  "object": "search",
  "id": "srch_9dm2pq4x1a",
  "status": "succeeded",
  "depth": "standard",
  "query": "How does climate change affect biodiversity?",
  "paper_count": 20,
  "credits_cost": 5,
  "answer": {
    "object": "answer",
    "text": "Warming interacts with habitat fragmentation to accelerate local extinctions [1]. Range shifts toward poles and higher elevations are widely documented [2] …",
    "citations": [
      {
        "index": 1,
        "quote": "…warming interacts with habitat fragmentation to accelerate local extinction risk…",
        "source": {
          "type": "paper",
          "id": "pap_3kf9wq2m8x",
          "title": "Climate-driven range shifts and local extinction risk",
          "doi": "10.1038/s41558-019-0456-2"
        },
        "locations": [
          { "page": 4, "bbox": { "x": 0.14, "y": 0.31, "width": 0.72, "height": 0.04 } }
        ]
      }
      …
    ],
    "unsourced_claim_count": 0
  },
  "created_at": "2026-08-11T09:14:22Z",
  "completed_at": "2026-08-11T09:14:29Z",
  "error": null
}

Retrieve, list, cancel, results, export

GET /v1/searches/{id}

Returns the full object, including status. Free, and safe to poll with backoff.

cURL

curl "https://api.scispace.com/v1/searches/srch_9dm2pq4x1a" \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01"

GET /v1/searches

Cursor-paginated, newest first. status and created_after narrow the set.

cURL

curl "https://api.scispace.com/v1/searches?limit=20&status=succeeded" \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01"

json

{
  "object": "list",
  "data": [ { "object": "search", "id": "srch_9dm2pq4x1a", "status": "succeeded" } ],
  "has_more": true,
  "next_cursor": "srch_7bk1lm5z3c"
}

POST /v1/searches/{id}/cancel

Stops a queued or running search. Terminal searches return 409 search_not_cancelable.

cURL

curl -X POST "https://api.scispace.com/v1/searches/srch_9dm2pq4x1a/cancel" \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01"

Cancelling still charges for work already done

You are billed for the papers already processed, not the full depth price.

GET /v1/searches/{id}/results

The ranked papers behind the answer, separate from the answer itself so you can screen them. Cursor-paginated; each row is a Paper plus its relevance score.

cURL

curl "https://api.scispace.com/v1/searches/srch_9dm2pq4x1a/results?limit=2" \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01"

json

{
  "object": "list",
  "data": [
    {
      "object": "search_result",
      "rank": 1,
      "relevance_score": 0.94,
      "paper": { "object": "paper", "id": "pap_3kf9wq2m8x", "title": "Climate-driven range shifts…" }
    }
  ],
  "has_more": true,
  "next_cursor": "pap_6wq0nc2v8t"
}

POST /v1/searches/{id}/export

Renders the result set to a File. Formats: csv, xlsx, bibtex, ris. Free.

cURL

curl -X POST "https://api.scispace.com/v1/searches/srch_9dm2pq4x1a/export" \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -d '{"format":"csv"}'

json

{
  "object": "file",
  "id": "file_qwqxq7ix10",
  "filename": "searches-srch_9dm2pq4x1a.csv",
  "byte_size": 18244,
  "download_url": "https://files.scispace.com/exports/file_qwqxq7ix10.csv?sig=…",
  "expires_at": "2026-08-11T10:14:22Z",
  "created_at": "2026-08-11T09:14:22Z"
}

Download URLs expire after 1 hour

Fetch the file, or re-request the export. Do not store the URL.

Errors

Status	`code`	When	Fix
400	`parameter_missing`	no `query`	send `query`
400	`query_too_long`	over 1,000 characters	shorten the query
402	`insufficient_credits`	balance exhausted	top up; pricing-and-credits
409	`search_not_cancelable`	already terminal	none
429	`rate_limit_exceeded`	throughput	back off; rate-limits

Limits and cost

Depth	Credits	`max_papers` ceiling	Latency p50	Latency p95
`standard`	5	20	6 s	15 s
`high_quality`	15	50	20 s	45 s
`deep_review`	60	200	90 s	240 s

query is capped at 1,000 characters. Searches and their results are retained for 90 days (7 days for test keys), after which the ID returns 404 resource_expired. Cancelling still charges for work already done. Exports are free and their download URLs expire after 1 hour.

search · answer · depth · literature-review-agent · streaming-deep-review

Last updated 2026-08-10

When to use

When not to use

Endpoints

The search object

Fields

Parameters

Create a search

Retrieve, list, cancel, results, export

GET /v1/searches/{id}

GET /v1/searches

POST /v1/searches/{id}/cancel

GET /v1/searches/{id}/results

POST /v1/searches/{id}/export

Errors

Limits and cost

Related