---
title: "Query Assistant For Polling"
method: POST
path: "/api_partner/assistant/poll"
tags: ["Assistant"]
---

# Query Assistant For Polling

`POST /api_partner/assistant/poll`

Submit a question to the scite Assistant. Returns a task ID that you poll via `GET /api_partner/assistant/tasks/{task_id}`.

## Required Fields

### `turns` — Conversation History

The conversation history as a list of turn objects. Each turn has a `role` (`"user"` or `"assistant"`) and `content`. For a new conversation, provide a single user turn:

```json
{
  "turns": [{"role": "user", "content": "How does protein structure affect function?"}]
}
```

For multi-turn conversations, include the full history. Assistant turns should include `references`, `searchStrategy`, `model`, `settings`, and `publicationsConsulted` from previous responses.

### `userInput` — Current Question

The current user question (should match the last user turn's content). Used independently for search strategy generation and tool selection.

---

## Reference Behavior Control

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `alwaysUseReferences` | bool | false | Force reference retrieval even for non-scientific questions |
| `neverUseReferences` | bool | false | Skip reference retrieval entirely (takes precedence over `alwaysUseReferences`) |
| `numReferences` | int | 25 | Maximum reference passages to include in LLM context |
| `referenceChecks` | list[str] | [] | Celery task IDs from uploaded documents (reference check feature) |
| `searches` | list[str] | [] | Pre-defined search queries (skips auto-generation) |

---

## Search Filtering

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `yearFrom` / `yearTo` | str or null | null | Filter by date range (4-digit year or ISO date) |
| `topics` | list[str] | [] | Filter by research topics |
| `citationSections` | list[str] | [] | Filter citations by paper section: `results`, `discussion`, `conclusion`, `methods`, `introduction` |
| `publicationTypes` | list[str] | [] | Filter by type: `review`, `systematic review`, `meta-analysis`, `practice guideline`, `journal-article`, etc. |
| `journals` | list[str] | [] | Filter to specific journal names |
| `openAccessOnly` | bool | false | Only return open access publications |
| `abstractsOnly` | bool | false | Only use paper abstracts (excludes citation statements) |
| `fullTextsOnly` | bool | false | Only use citation statements (excludes abstracts) |

---

## Paper Selection

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `dois` | list[str] | [] | Specific DOIs to scope the search to. DOIs in `userInput` are auto-extracted and merged. |
| `dashboards` | list[int] | [] | Collection (dashboard) IDs to pull DOIs from. Requires authenticated user with access. |

---

## Result Ranking — `rankBy`

Controls how retrieved results are ranked before being passed to the LLM. Default: `"all"`.

| Value | Ranking Strategy |
|-------|-----------------|
| `all` | Balanced: relevance + total citations + scite index + date + supporting + contrasting |
| `relevance` | Semantic relevance only |
| `date` | Recency + relevance |
| `citations` | Total citation count + relevance |
| `supporting-citations` | Supporting citation count + relevance |
| `contrasting-citations` | Contrasting citation count + relevance |
| `journal-rank` | Scite journal index + relevance |

---

## Response Configuration

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `answerLength` | str | `"short"` | `"short"` (~100-200 words), `"medium"` (comprehensive), or `"long"` (exhaustive) |
| `model` | str or null | `gpt-5-nano-2025-08-07` | LLM model for response generation (see below) |
| `reasoningEffort` | str or null | null | `"minimal"`, `"low"`, `"medium"`, or `"high"` — only for reasoning models |

### Available Models

| Model ID | Provider | Notes |
|----------|----------|-------|
| `claude-sonnet-4-6` | Anthropic | 200K context, 64K max output |
| `claude-opus-4-6` | Anthropic | 200K context, 128K max output |
| `claude-sonnet-4-5-20250929` | Anthropic | 200K context, 64K max output |
| `claude-opus-4-5-20251101` | Anthropic | 200K context, 64K max output |
| `claude-haiku-4-5-20251001` | Anthropic | 200K context, 64K max output |
| `gpt-5-nano-2025-08-07` | OpenAI | **Default.** 400K context. Reasoning model |
| `gpt-5-mini-2025-08-07` | OpenAI | 400K context. Reasoning model |
| `gpt-5.2-2025-12-11` | OpenAI | 400K context. Reasoning model. Supports `reasoningEffort` |

If one provider fails, the system automatically falls back to the other. Unsupported or retired model strings automatically fall back to the default (`gpt-5-nano-2025-08-07`).

---

## Structured Response Mode

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `useStructuredResponse` | bool | false | Return per-reference structured data instead of prose |
| `jsonResponseType` | str or null | null | `null` (full detail), `"concise"`, or `"boolean"` (yes/no screening) |
| `reprocessTurnIdx` | int or null | null | Index of an existing turn to reprocess |
| `columnSlug` | str or null | null | Slug of a specific column to reprocess |

---

## Patent Modes

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `usePatentMode` | bool | false | Search patents only (no academic papers) |
| `useMixedPatentMode` | bool | false | Search both patents and academic papers |

---

## Session Management

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `sessionId` | int or null | null | Existing session ID to continue a conversation |

---

## Response

Returns `{"id": "<task_id>"}`. If the user is rate-limited, also includes `"usage": {"used": N, "max": M}`.

---

## Examples

**Basic single question:**
```json
{
  "turns": [{"role": "user", "content": "What is the effect of exercise on depression?"}],
  "userInput": "What is the effect of exercise on depression?"
}
```

**DOI-scoped question:**
```json
{
  "turns": [{"role": "user", "content": "Summarize the key findings"}],
  "userInput": "Summarize the key findings",
  "dois": ["10.1002/cepa.3344", "10.1002/hsr2.70931"]
}
```

**Filtered search:**
```json
{
  "turns": [{"role": "user", "content": "What do systematic reviews say about mindfulness for anxiety?"}],
  "userInput": "What do systematic reviews say about mindfulness for anxiety?",
  "publicationTypes": ["systematic review", "meta-analysis"],
  "yearFrom": "2020",
  "rankBy": "supporting-citations",
  "answerLength": "long"
}
```

**Structured response (table mode):**
```json
{
  "turns": [{"role": "user", "content": "Does each paper support the hypothesis that X causes Y?"}],
  "userInput": "Does each paper support the hypothesis that X causes Y?",
  "useStructuredResponse": true,
  "jsonResponseType": "boolean",
  "dois": ["10.1234/a", "10.1234/b", "10.1234/c"]
}
```

## Headers

- `authorization` string — Set to `Bearer <token>` to pass token for authorization.

## Request body

- AssistantRequestSchema
  - `alwaysUseReferences` boolean
  - `neverUseReferences` boolean
  - `abstractsOnly` boolean
  - `fullTextsOnly` boolean
  - `numReferences` integer
  - `rankBy` 'all' | 'relevance' | 'date' | 'citations' | 'supporting-citations' | 'contrasting-citations' | 'journal-rank'
  - `answerLength` 'short' | 'medium' | 'long'
  - `model` string, nullable
  - `reasoningEffort` 'minimal' | 'low' | 'medium' | 'high'
  - `citationStyle` 'apa' | 'ieee' | 'mla' | 'ama' | 'chicago' | 'harvard' | 'vancouver' | 'bibtex'
  - `yearFrom` string, nullable
  - `yearTo` string, nullable
  - `topics` string[]
  - `journals` string[]
  - `citationSections` string[]
  - `publicationTypes` string[]
  - `dashboards` integer[]
  - `referenceChecks` string[]
  - `dois` string[]
  - `useStructuredResponse` boolean
  - `usePatentMode` boolean
  - `useMixedPatentMode` boolean
  - `sessionId` integer, nullable
  - `turns` TurnSchemaInput[], required
    - `role` string, nullable
    - `content` string, nullable
    - `sections` string[], nullable
    - `structuredResponse` unknown[], nullable
      - unknown
    - `references` SciteapiModelsAssistantReferenceSchema[]
      - `answer` string, required
      - `texts` string[], required
      - `textSources` string[], nullable
      - `context` string, required
      - `title` string, required
      - `doi` string, required
      - `link` string, required
      - `type` string
      - `paper` SearchResultSchemaWithDateStrInput, required
        - `id` string, nullable
        - `doi` string, nullable
        - `title` string, nullable
        - `slug` string, nullable
        - `authors` AuthorResults[], nullable
          - `authorName` string, nullable
          - `authorSlug` string, nullable
          - `authorSequenceNumber` union
            - string
            - integer
          - `affiliation` string, nullable
          - `affiliationSlug` string, nullable
        - `journal` string, nullable
        - `shortJournal` string, nullable
        - `publisher` string, nullable
        - `memberId` integer, nullable
        - `abstract` string, nullable
        - `year` integer, nullable
        - `date` string, nullable
        - `lastUpdate` integer, nullable
        - `volume` string, nullable
        - `issue` string, nullable
        - `page` string, nullable
        - `tally` TallyResponse
          - `total` integer, required
          - `supporting` integer, required
          - `contradicting` integer, required
          - `mentioning` integer, required
          - `unclassified` integer, required
          - `doi` string, nullable
          - `citingPublications` integer, nullable
        - `issns` string[], nullable
        - `editorialNotices` EditorialNoticeSchema[]
          - `status` string, nullable
          - `date` string, nullable
          - `noticeDoi` string, nullable
          - `doi` string, required
          - `urls` string[], nullable
        - `normalizedTypes` string[]
        - `isOa` boolean
        - `oaStatus` string
        - `meshTypes` PubmedMeshTypeResponse[]
          - `descriptorId` string, required
          - `descriptorName` string, required
          - `qualifierId` string, nullable
          - `qualifierName` string, nullable
        - `relevancyScore` number, nullable
        - `citations` CitationSearch[]
          - `id` integer, nullable
          - `source` string, required
          - `target` string, required
          - `negative` number, nullable
          - `positive` number, nullable
          - `neutral` number, nullable
          - `section` string, nullable
          - `expertClassification` string, nullable
          - `type` string, nullable
          - `typeConfidence` number, nullable
          - `snippet` string, required
          - `lang` string, nullable
          - `langConfidence` number, nullable
          - `refLocation` string, nullable
          - `memberId` integer, nullable
          - `selfCites` SelfCiteSchema[]
            - `type` string, nullable, required
            - `family` string, nullable, required
            - `given` string, nullable, required
          - `snippetHidden` boolean
        - `fulltextExcerpts` string[]
        - `highlightedFields` string[]
      - `patent` object, nullable
      - `refCheckId` string, nullable
      - `included` boolean, nullable
      - `reason` string, nullable
    - `feedback` FeedbackSchema
      - `feedbackType` 'positive' | 'negative'
      - `reason` string, nullable
    - `searchStrategy` string[], nullable
    - `warning` string, nullable
    - `model` string, nullable
    - `settings` object, nullable
    - `publicationsConsulted` object[], nullable
    - `columns` StructuredColumn[], nullable
      - `name` string, required
      - `slug` string, required
      - `instructions` string, nullable
      - `type` 'response' | 'dynamic'
      - `order` integer
      - `json_response_type` 'concise' | 'boolean', nullable
  - `userInput` string, required
  - `searches` string[]
  - `openAccessOnly` boolean
  - `jsonResponseType` 'concise' | 'boolean', nullable
  - `reprocessTurnIdx` integer, nullable
  - `columnSlug` string, nullable
  - `anonId` string, nullable
  - `recaptchaToken` string, nullable
  - `country` string, nullable
  - `saveSession` boolean

## Response `200`

Successful Response

- AssistantPollingResponseSchema
  - `id` string, nullable
  - `info` AssitantPollingInfo
    - `step` string, nullable
    - `stepNumber` integer, nullable
    - `response` string, nullable
    - `structuredResponse` unknown[], nullable
      - unknown
    - `searches` string[], nullable
    - `publicationsUsed` string[], nullable
    - `publicationsConsulting` string[], nullable
    - `currentSearch` string, nullable
    - `dois` string[], nullable
    - `factChecks` FactCheck
      - `used` unknown[], nullable
        - unknown
      - `rejected` unknown[], nullable
        - unknown
  - `status` string, nullable
  - `result` AssistantResponseSchema
    - `title` string, nullable
    - `sessionId` integer, nullable
    - `turns` TurnSchemaOutput[]
      - `role` string, nullable
      - `content` string, nullable
      - `sections` string[], nullable
      - `structuredResponse` unknown[], nullable
        - unknown
      - `references` SciteapiModelsAssistantReferenceSchemaOutput[]
        - `answer` string, required
        - `texts` string[], required
        - `textSources` string[], nullable
        - `context` string, required
        - `title` string, required
        - `doi` string, required
        - `link` string, required
        - `type` string
        - `paper` SearchResultSchemaWithDateStrOutput, required
          - `id` string, nullable
          - `doi` string, nullable
          - `title` string, nullable
          - `slug` string, nullable
          - `authors` AuthorResults[], nullable
            - `authorName` string, nullable
            - `authorSlug` string, nullable
            - `authorSequenceNumber` union
              - …
            - `affiliation` string, nullable
            - `affiliationSlug` string, nullable
          - `journal` string, nullable
          - `shortJournal` string, nullable
          - `publisher` string, nullable
          - `memberId` integer, nullable
          - `abstract` string, nullable
          - `year` integer, nullable
          - `date` string, nullable
          - `lastUpdate` integer, nullable
          - `volume` string, nullable
          - `issue` string, nullable
          - `page` string, nullable
          - `tally` TallyResponse
            - `total` integer, required
            - `supporting` integer, required
            - `contradicting` integer, required
            - `mentioning` integer, required
            - `unclassified` integer, required
            - `doi` string, nullable
            - `citingPublications` integer, nullable
          - `issns` string[], nullable
          - `editorialNotices` EditorialNoticeSchema[]
            - `status` string, nullable
            - `date` string, nullable
            - `noticeDoi` string, nullable
            - `doi` string, required
            - `urls` string[], nullable
          - `normalizedTypes` string[]
          - `isOa` boolean
          - `oaStatus` string
          - `meshTypes` PubmedMeshTypeResponse[]
            - `descriptorId` string, required
            - `descriptorName` string, required
            - `qualifierId` string, nullable
            - `qualifierName` string, nullable
          - `relevancyScore` number, nullable
          - `citations` CitationSearch[]
            - `id` integer, nullable
            - `source` string, required
            - `target` string, required
            - `negative` number, nullable
            - `positive` number, nullable
            - `neutral` number, nullable
            - `section` string, nullable
            - `expertClassification` string, nullable
            - `type` string, nullable
            - `typeConfidence` number, nullable
            - `snippet` string, required
            - `lang` string, nullable
            - `langConfidence` number, nullable
            - `refLocation` string, nullable
            - `memberId` integer, nullable
            - `selfCites` SelfCiteSchema[]
              - …
            - `snippetHidden` boolean
          - `fulltextExcerpts` string[]
          - `highlightedFields` string[]
        - `patent` object, nullable
        - `refCheckId` string, nullable
        - `included` boolean, nullable
        - `reason` string, nullable
      - `feedback` FeedbackSchema
        - `feedbackType` 'positive' | 'negative'
        - `reason` string, nullable
      - `searchStrategy` string[], nullable
      - `warning` string, nullable
      - `model` string, nullable
      - `settings` object, nullable
      - `publicationsConsulted` object[], nullable
      - `columns` StructuredColumn[], nullable
        - `name` string, required
        - `slug` string, required
        - `instructions` string, nullable
        - `type` 'response' | 'dynamic'
        - `order` integer
        - `json_response_type` 'concise' | 'boolean', nullable
    - `turnsTotal` integer, nullable
    - `turnsOffset` integer, nullable
    - `lastUpdated` string, date, nullable
    - `shareToken` string, nullable
    - `createdAt` string, date, nullable
    - `hasUploadedReferences` boolean
    - `slug` string, required
  - `error` string, nullable
  - `usage` AssistantUsageSchema
    - `used` integer, required
    - `max` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/scite/apis/scite-api.md) · [All operations](https://skmtc.net/scite/apis/scite-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scite/scite-api/revisions/9f4cba020e89/schema)