Topics

Extract the concepts that matter for a query, each with the evidence behind it.

Endpoints

Method	Path	Scope	Credits	Description
POST	`/v1/topic-searches`	`topics:write`	4 / 12 by depth	Create (async)
GET	`/v1/topic-searches/{id}`	`topics:read`	0	Retrieve topics + evidence

This endpoint is asynchronous

Returns 202; poll or use a webhook.

Parameters

Parameter	Type	Required	Description
`query`	string	yes	The area to map
`max_topics`	integer	no	Default 5, maximum 20
`language`	string	no

Response

json

{
  "object": "topic_search",
  "id": "tsrch_3pcptfwlcv",
  "status": "succeeded",
  "query": "How does climate change affect biodiversity?",
  "topic_count": 3,
  "credits_cost": 4,
  "topics": [
    {
      "object": "topic",
      "id": "top_2808be1c6d",
      "name": "Range shifts",
      "description": "Poleward and upslope movement of species distributions tracking isotherms.",
      "evidence": [
        {
          "quote": "…species have shifted their ranges poleward by 16.9 km per decade on average…",
          "source": { "type": "paper", "id": "pap_3kf9wq2m8x", "title": "Climate-driven range shifts" },
          "locations": [ { "page": 2, "bbox": { "x": 0.11, "y": 0.55, "width": 0.78, "height": 0.03 } } ]
        }
      ]
    },
    {
      "object": "topic",
      "id": "top_91ad4fe07b",
      "name": "Phenological mismatch",
      "description": "Decoupling of seasonal timing between interacting species.",
      "evidence": [
        {
          "quote": "…budburst advanced 8 days while caterpillar emergence advanced 15…",
          "source": { "type": "paper", "id": "pap_6wq0nc2v8t", "title": "Trophic asynchrony under warming" },
          "locations": [ { "page": 6, "bbox": {} } ]
        }
      ]
    },
    {
      "object": "topic",
      "id": "top_5cd10ba934",
      "name": "Ocean deoxygenation",
      "description": "Falling dissolved oxygen compressing viable habitat for large pelagic species.",
      "evidence": [
        { "quote": null, "source": { "type": "model" }, "locations": [] }
      ]
    }
  ]
}

Topics are ordered by evidential weight, strongest first — not alphabetically, and not by frequency. The ordering is stable for a given query.

Field	Type	Description
`topics[].name`	string	Two or three words. Suitable as a facet label
`topics[].description`	string	One sentence, in the literature's own vocabulary
`topics[].evidence[]`	array	Supporting spans. May be empty — see below
`topics[].evidence[].quote`	string	Verbatim from the source. `null` when `source.type` is `model`
`topics[].evidence[].source.type`	enum	`paper`, `document`, or `model`

Topics sourced from the model

The third topic above has source.type: "model" and no quote. That means the topic was inferred from the shape of the result set rather than lifted from any single paper — a real pattern the corpus supports collectively, but with no one passage to point at.

Treat these as suggestions, not findings:

Never render them with the citation affordance you use for paper and document evidence.
Label them in the UI. "Suggested by SciSpace" is honest; silence is not.
Exclude them from systematic-review pipelines, where every row needs a locator.

Python

grounded = [t for t in topic_search.topics
            if any(e.source.type != "model" for e in t.evidence)]

Use cases

Query expansion before a search
Taxonomy or landscape mapping
Gap-finding: topics with thin evidence are where the literature is quiet

topic · searches

Last updated 2026-08-10