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

# Create a new systematic review

`POST /sessions/systematic-reviews`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/sessions/systematic-reviews`
- Auth: HTTP bearer

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.

Two options are chosen by the person requesting the review rather than by the client calling this endpoint: the screening `depth` at each stage and `extraction.useFigures`, both of which require higher usage when enabled. Set them explicitly rather than relying on the defaults — the examples below do — and check the `settings` block in the response to confirm what the review is actually running with.

### 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, "depth": "thorough" },
  "fulltextScreening": { "reuseAbstractCriteria": true, "depth": "thorough" },
  "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` applies the criteria in full, records the quotes behind each decision, and requires higher usage. `fast` returns decisions without supporting quotes and wrongly excludes more papers that met your criteria. The person you are acting for chooses this — do not decide it yourself. If they asked for a thorough screen, set `thorough`; if they asked for a fast one, set `fast`; if they have not said, ask them rather than picking silently. Omitting this field means `thorough`, so state your choice explicitly and tell the person which depth the review will use.
  - `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, with the same trade-off as `abstractScreening.depth`: `thorough` applies the criteria in full, records the quotes behind each decision, and requires higher usage; `fast` returns decisions without supporting quotes and wrongly excludes more papers that met your criteria. The person you are acting for chooses this — do not decide it yourself, and ask them if they have not said which they want. Omitting this field means `thorough`.
  - `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: Whether Elicit also reads figures and charts when answering your extraction questions, so it can pick up results that appear only in a figure — dose-response curves, Kaplan-Meier plots, anything whose answer lives in the image. It applies to every extraction column on every included paper, makes extraction slower, and requires higher usage. The person you are acting for chooses this — do not turn it on of your own accord. If they asked for figures, set it to `true` without hesitation; if they have not said, ask them. Omitting this field means figures are not read. 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
  - `settings` object, required: The screening depth and figure settings this review was created with, after defaults were applied. `null` means that stage was not configured. Report these back to the person who asked for the review.
    - `abstractScreeningDepth` 'fast' | 'thorough' | 'null', nullable, required
    - `fulltextScreeningDepth` 'fast' | 'thorough' | 'null', nullable, required
    - `useFigures` boolean, nullable, required
  - `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. Only the owner can use it; a shared recipient receives 404 even when this link is present.

## 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. For credits-based accounts, and for organization members with a weekly workflow-run limit, `error.details.reason` says why (`credits_exhausted` or `spend_limit_reached`) and `error.details.resetsAt` when the block lifts.
- `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`).
- `429`: Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500`: An unexpected error occurred. Retry reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-16** `22847bf7e65d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/changes/sessions/systematic-reviews/post.md)

---

[API](https://skmtc.dev/elicitlabs/apis/elicit-labs-api.md) - [All operations](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/revisions/cbbe29509d04?raw)