# 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 |

> [!info] 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]. 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 in isolated populations.",
        "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
            }
          }
        ]
      },
      {
        "index": 2,
        "quote": "Species have shifted their ranges poleward by 16.9 km per decade on average.",
        "source": {
          "type": "paper",
          "id": "pap_6wq0nc2v8t",
          "title": "Rapid range shifts of species associated with high levels of climate warming",
          "doi": "10.1126/science.1206432"
        },
        "locations": [
          {
            "page": 2,
            "bbox": {
              "x": 0.11,
              "y": 0.55,
              "width": 0.78,
              "height": 0.03
            }
          }
        ]
      }
    ],
    "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. `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

```bash
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 }
  }'
```

```python
from scispace import Scispace

client = Scispace()

search = client.searches.create(
    query="How does climate change affect biodiversity?",
    depth="standard",
    max_papers=20,
    filters={"year_from": 2015, "open_access": True},
).wait(timeout=60)

print(search.answer.text)
```

```typescript
import Scispace from "scispace";

const client = new Scispace();

const search = await client.searches
  .create({
    query: "How does climate change affect biodiversity?",
    depth: "standard",
    max_papers: 20,
    filters: { year_from: 2015, open_access: true },
  })
  .wait({ timeoutMs: 60_000 });

console.log(search.answer.text);
```

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 in isolated populations.",
        "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
            }
          }
        ]
      },
      {
        "index": 2,
        "quote": "Species have shifted their ranges poleward by 16.9 km per decade on average.",
        "source": {
          "type": "paper",
          "id": "pap_6wq0nc2v8t",
          "title": "Rapid range shifts of species associated with high levels of climate warming",
          "doi": "10.1126/science.1206432"
        },
        "locations": [
          {
            "page": 2,
            "bbox": {
              "x": 0.11,
              "y": 0.55,
              "width": 0.78,
              "height": 0.03
            }
          }
        ]
      }
    ],
    "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.

```bash
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.

```bash
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`.

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

> [!warning] 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.

```bash
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 and local extinction risk"
      }
    }
  ],
  "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.

```bash
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=c2ln5f8a91b03e7d44c6",
  "expires_at": "2026-08-11T10:14:22Z",
  "created_at": "2026-08-11T09:14:22Z"
}
```

> [!info] 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.

## Related

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