> ## Documentation Index > Fetch the complete documentation index at: https://docs.consensus.app/llms.txt > Use this file to discover all available pages before exploring further. # Start a Thread > Delegate a research task to the Consensus research agent and get a `thread_id` back immediately. Rate limit: 1 request/second. The run is asynchronous: poll `GET /v1/threads/{thread_id}` until status is `idle`. A 5xx means the request may or may not have taken effect: there is no idempotency key yet, so a blind retry can create a second Thread. ## OpenAPI ````yaml /openapi.json post /v1/threads openapi: 3.1.0 info: title: Consensus API description: >- Search usage is billed in calls: one call per 100 papers returned, rounded up, with a minimum of 1 call per request. Usage counts against your plan's included monthly calls. Free plans include 30 calls per month, Pro and Teams plans include 500, and Deep plans include 2,000. Paid plans with an active metered API subscription may continue past the included limit; additional calls are billed at $0.05 per call. Enterprise API keys have unlimited access. version: '1.0' servers: - url: https://api.consensus.app security: [] paths: /v1/threads: post: summary: Start a Thread description: >- Delegate a research task to the Consensus research agent and get a `thread_id` back immediately. Rate limit: 1 request/second. The run is asynchronous: poll `GET /v1/threads/{thread_id}` until status is `idle`. A 5xx means the request may or may not have taken effect: there is no idempotency key yet, so a blind retry can create a second Thread. operationId: v1_create_thread requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ThreadCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ThreadDispatchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - XApiKeyHeader: [] components: schemas: ThreadCreateRequest: properties: input_message: type: string maxLength: 10000 minLength: 1 title: Input Message description: >- The complete research brief. The agent is autonomous and asks no follow-up questions, so include the whole task in one message. mode: type: string enum: - pro - deep title: Mode description: >- Agent depth. `pro` (~20 papers) for almost all requests; `deep` (~50 papers, structured report) requires a paid plan. default: pro filters: anyOf: - $ref: '#/components/schemas/ThreadFilters' - type: 'null' attachments: anyOf: - $ref: '#/components/schemas/ThreadAttachments' - type: 'null' additionalProperties: false type: object required: - input_message title: ThreadCreateRequest description: POST /v1/threads body. ThreadDispatchResponse: properties: thread_id: type: string title: Thread Id interaction_id: type: string title: Interaction Id created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At title: anyOf: - type: string - type: 'null' title: Title description: Auto-generated Thread title. status: type: string enum: - running - idle - failed title: Status description: Always `running` on dispatch. mode: type: string enum: - pro - deep title: Mode url: type: string title: Url description: Deep-link to the Thread on consensus.app. poll_after_seconds: type: integer title: Poll After Seconds description: Recommended wait between `GET /v1/threads/{thread_id}` polls. max_wait_seconds: type: integer title: Max Wait Seconds description: Suggested polling ceiling before giving up (~180 pro, ~600 deep). type: object required: - thread_id - interaction_id - status - mode - url - poll_after_seconds - max_wait_seconds title: ThreadDispatchResponse description: POST /v1/threads and POST /v1/threads/{thread_id}/interactions. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ThreadFilters: properties: year_min: anyOf: - type: integer - type: 'null' title: Year Min description: Exclude papers before this year. year_max: anyOf: - type: integer - type: 'null' title: Year Max description: Exclude papers after this year. month_min: anyOf: - type: integer maximum: 12 minimum: 1 - type: 'null' title: Month Min description: Earliest publication month, paired with `year_min`. month_max: anyOf: - type: integer maximum: 12 minimum: 1 - type: 'null' title: Month Max description: Latest publication month, paired with `year_max`. study_types: anyOf: - items: $ref: '#/components/schemas/StudyTypeKeywordEnum' type: array - type: string - type: 'null' title: Study Types description: >- Only include these study types — a list, or a comma-separated string (e.g. `rct,meta-analysis`). domain: anyOf: - type: string - type: 'null' title: Domain description: Restrict to a field of study. country: anyOf: - type: string - type: 'null' title: Country description: >- Comma-separated ISO 3166-1 alpha-2 country codes (e.g. us, gb). Unknown codes are ignored. human: anyOf: - type: boolean - type: 'null' title: Human description: Only include human studies. controlled: anyOf: - type: boolean - type: 'null' title: Controlled description: Only include controlled studies. sample_size_min: anyOf: - type: integer minimum: 1 - type: 'null' title: Sample Size Min description: Exclude studies with smaller sample sizes. sjr_min: anyOf: - type: integer maximum: 4 minimum: 1 - type: 'null' title: Sjr Min description: Exclude journals in better quartiles (1 is best). sjr_max: anyOf: - type: integer maximum: 4 minimum: 1 - type: 'null' title: Sjr Max description: Exclude journals in lesser quartiles (1 is best). citation_min: anyOf: - type: integer - type: 'null' title: Citation Min description: Exclude papers with fewer citations. duration_min: anyOf: - type: integer - type: 'null' title: Duration Min description: Minimum study duration (days). duration_max: anyOf: - type: integer - type: 'null' title: Duration Max description: Maximum study duration (days). exclude_preprints: anyOf: - type: boolean - type: 'null' title: Exclude Preprints description: Exclude preprints; only peer-reviewed papers. open_access: anyOf: - type: boolean - type: 'null' title: Open Access description: Only include open-access papers. clinical_guideline: anyOf: - type: boolean - type: 'null' title: Clinical Guideline description: Restrict to clinical guidelines. publisher_name: anyOf: - type: string - type: 'null' title: Publisher Name description: Restrict to a publisher. journal_name: anyOf: - type: string - type: 'null' title: Journal Name description: Restrict to a journal. additionalProperties: false type: object title: ThreadFilters description: >- Global filters applied to every search the agent runs (shared /v1/search vocabulary). Field set must match the filter fields of ``features/quick_search/schema.py:QuickSearchSearchParams`` (the RFC says the two surfaces share one filter schema); parity is pinned by ``schema_test.py``. Values are validated here, not just typed: downstream parsers silently drop unknown domain/study-type values, and an expensive agent run must not execute without a restriction the caller asked for. ThreadAttachments: properties: paper_ids: anyOf: - items: type: string type: array maxItems: 50 - type: 'null' title: Paper Ids description: Paper ids to focus the research on. collection_ids: anyOf: - items: type: integer type: array maxItems: 10 - type: 'null' title: Collection Ids description: Library collection ids to focus on. additionalProperties: false type: object title: ThreadAttachments description: Scope the research to specific papers/collections. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError StudyTypeKeywordEnum: type: string enum: - bench experiment - case report - case study - case-control study - cohort study - commentary or perspective - cross-sectional study - field study - historical or archival analysis - interview study - literature review - longitudinal / panel data study - meta-analysis - mixed methods study - non-randomized experimental study - non-rct in vitro - other - rct - systematic review - theoretical, modeling, or simulation study - non-rct experimental - non-rct observational study - animal title: StudyTypeKeywordEnum description: All possible study types strings saved to search index documents. securitySchemes: XApiKeyHeader: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.