---
title: "Create a new systematic review"
method: POST
path: "/sessions/systematic-reviews"
tags: ["Systematic Reviews"]
---

# Create a new systematic review

`POST /sessions/systematic-reviews`

Start a systematic review. Elicit runs the stages you configure — searches, abstract screening, fulltext screening, extraction, and a report. Each stage runs only when you include it; omit a stage to skip it. The default example below runs a complete review end-to-end.

Systematic reviews are long-running operations. The response includes a `sessionId` and a `links.self` URL (`/api/v2/sessions/systematic-reviews/:sessionId`) that you poll for status. You can also watch progress live at the `url` in the response.

### Plan limits

| Plan | Max columns | Max results per query | Max total results | Figure extraction |
|------|-------------|----------------------|-------------------|-------------------|
| Pro | 20 | 1,000 | 5,000 | No |
| Scale | 30 | 5,000 | 20,000 | Yes |
| Enterprise | 40 | 10,000 | 40,000 | Yes |

### Example

```bash
curl -X POST https://elicit.com/api/v2/sessions/systematic-reviews \
-H "Authorization: Bearer elk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
  "researchQuestion": "Do GLP-1 receptor agonists reduce MACE in T2D patients?",
  "searches": [{ "query": "GLP-1 cardiovascular outcomes", "maxResults": 200 }],
  "abstractScreening": { "generate": true },
  "fulltextScreening": { "reuseAbstractCriteria": true },
  "extraction": { "generate": true, "useFigures": false },
  "generateReport": true
}'
```

## Request body

- object
  - `researchQuestion` string, required — The research question the review is investigating.
  - `protocolDetails` string — Free-form context (PICO, methodology, inclusion/exclusion rationale) used when Elicit generates screening criteria, extraction columns, or the final report.
  - `searches` object[] — Searches that feed the review pipeline. If omitted or empty, Elicit runs a semantic search using `researchQuestion` as the query. Total search results are subject to plan-specific limits.
    - `query` string, required — Search query
    - `corpus` 'elicit' | 'pubmed' | 'clinical_trials' — Corpus to search. `elicit` (default) searches Elicit's full academic paper index, spanning most research domains. `pubmed` restricts results to PubMed. `clinical_trials` returns registered trials only.
    - `searchMode` 'semantic' | 'keyword' — `semantic` (default) uses vector-similarity retrieval; `keyword` uses literal keyword matching.
    - `maxResults` integer — Maximum number of papers to retrieve from this search. Plan-specific caps apply.
  - `abstractScreening` object — Abstract-stage screening. Supply `criteria`, `generate: true`, or both. Omit the field to skip.
    - `criteria` object[] — Explicit screening criteria.
      - `name` string, required — Short name for the criterion
      - `instructions` string, required — Plain-language instructions used to judge whether a paper meets this criterion
    - `generate` boolean — When true, Elicit generates additional screening criteria.
    - `depth` 'fast' | 'thorough' — How thoroughly Elicit judges each abstract against your criteria. `thorough` (default) applies the criteria in full and records the quotes behind each decision. `fast` costs a fraction as much per paper, but wrongly excludes more papers that met your criteria and returns decisions without supporting quotes — use it to triage a large candidate set, not for a final screen. Send the same request with `dryRun: true` to compare what each setting costs in credits.
  - `fulltextScreening` object — Fulltext-stage screening. Supply `criteria`, `reuseAbstractCriteria: true`, or both. Requires `abstractScreening` to be present. Omit to skip.
    - `criteria` object[] — Explicit fulltext-stage criteria.
      - `name` string, required — Short name for the criterion
      - `instructions` string, required — Plain-language instructions used to judge whether a paper meets this criterion
    - `reuseAbstractCriteria` boolean — When true, the abstract-stage criteria are also applied at the fulltext stage.
    - `depth` 'fast' | 'thorough' — How thoroughly Elicit judges each full text against your criteria. `thorough` (default) applies the criteria in full and records the quotes behind each decision. `fast` costs less per paper, but wrongly excludes more papers that met your criteria and returns decisions without supporting quotes. Send the same request with `dryRun: true` to compare what each setting costs in credits.
  - `extraction` object — Extraction stage. Supply `questions`, `generate`, or both. Omit to skip extraction entirely.
    - `questions` object[] — Explicit extraction columns.
      - `name` string, required — Column header for this extraction question
      - `instructions` string, required — Plain-language instructions describing what to extract
      - `choices` string[] — Optional fixed list of allowed answers. Omit for free-text extraction. When set, the model is constrained to one of these values.
    - `generate` boolean — When true, Elicit generates additional extraction columns.
    - `useFigures` boolean — When true, Elicit also reads figures and charts when answering your extraction questions, so it can pick up results that appear only in a figure. Extraction takes longer and costs extra credits on every column (returned as `figuresCredits` in a `dryRun` estimate). Requires a plan that includes figure extraction.
  - `generateReport` boolean — Generate a full report at the end of the review. Requires `extraction`.
  - `title` string — Optional title for the review.
  - `isPublic` boolean — Whether the review should be publicly accessible via its URL without authentication. Defaults to false.
  - `dryRun` false — Deprecated. Omit this field to create the review.

## Response `202`

Systematic review creation accepted. The review is now running asynchronously. Poll `links.self` for status.

- SystematicReviewSessionCreated
  - `type` 'systematicReview', required
  - `sessionId` string, uuid, required — The session ID (UUID) returned by the create endpoints and `GET /sessions`
  - `status` 'processing', required — Initial status is always processing
  - `url` string, required — URL to view the review in the Elicit web interface
  - `isPublic` boolean, required — Whether the review is publicly accessible via its URL without authentication
  - `links` SessionLinks, required
    - `self` string, required — API URL for this session's full status and results (the typed get endpoint for its type)
    - `resume` string — API URL to resume this session. Present only while the session is paused for insufficient quota.

## Other responses

- `400` — Invalid request. Check that the config matches the schema — e.g. each enabled stage has at least one source of material (`criteria` / `questions` and/or `generate`).
- `401` — Authentication failed. The API key is missing, invalid, revoked, or expired.
- `402` — Insufficient quota.
- `403` — Access denied. Either API access is not available on your plan, or the systematic-reviews surface requires features your plan does not include (guided flow, or figure extraction when `useFigures: true`).
- `500` — An unexpected error occurred. Retry after a short delay.

---

[API](https://skmtc.dev/elicit/apis/elicit-api.md) · [All operations](https://skmtc.dev/elicit/apis/elicit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/elicit/elicit-api/revisions/2b42624536e5/schema)