ELelicitlabs
Systematic Reviews

Get systematic review status and results

Changed on

Poll the status of a systematic review created via POST /api/v2/sessions/systematic-reviews.

Status transitions

  • processing — the pipeline is running. Watch progress at url.
  • pausedForInsufficientQuota — the account exceeded its usage limit mid-run. The review stays paused until resumed via the links.resume URL (or the Elicit web interface) once the limit is resolved.
  • completed — the pipeline finished. Stage-organized exports appear under data. Only stages that actually ran are included.
  • failed — something went wrong. The error field contains details. data may still contain exports for stages that completed before the failure.
  • unknown — status is not tracked (legacy or user-created).

Response shape

data can include stage outputs before status: "completed". exportsStatus describes cache availability, not whether every completed stage has been exported:

  • ready — a cached export manifest was served. It can be stale and omit newly completed stages; missing URLs do not prove that a stage did not run.
  • generating — exports are being generated and no cached downloads are available yet. Poll again later.
  • unavailable — export generation is temporarily unavailable. Retry the GET later; this is separate from the research session's status.

Poll every 30–60 seconds while processing. If the session is paused for insufficient quota, resolve the usage limit and POST to links.resume instead of continuing to poll for completion.

After completion, repoll for missing expected exports even when exportsStatus is ready. Wait at least 60 seconds before fetching this endpoint again: a manifest younger than the 60-second cooldown can be served without checking newly completed stages. Older cached manifests can also be served while another request regenerates exports or when regeneration or session-state loading fails. There is no fixed freshness guarantee. Check dataFreshness to detect an unchanged cache, but do not treat its timestamp alone as proof that every stage is exported. Use bounded retries with backoff; if expected URLs remain missing, report incomplete export availability rather than assuming the stages never ran.

  • data.search.{csv,xlsx} — gather-stage paper list.
  • data.screen.{csv,xlsx} — abstract-screening results.
  • data.fulltext.{csv,xlsx} — fulltext-screening results (only when fulltext screening is configured).
  • data.extract.{csv,xlsx} — extraction-stage results.
  • data.report — structured content under result, plus optional pdf / docx / txt (APA reference list) / bib (BibTeX) / ris presigned download URLs.

All stage URLs are presigned for 7 days and serve with Content-Disposition: attachment so browser downloads land with the canonical filename.

dataFreshness is the ISO timestamp of the cached export manifest used for this response, or null when no timestamp is available for the returned data. It is not the session's completion time or a guarantee of current exports.

Including the full report body

By default, data.report.result.reportBody and data.report.result.abstract are omitted to keep responses light. Append ?include=reportBody to include them.

get/sessions/systematic-reviews/{sessionId}

Request

  • Base URL
    https://elicit.com/api/v2
  • URL
    https://elicit.com/api/v2/sessions/systematic-reviews/{sessionId}
  • Auth
    HTTP bearer

Path parameters

sessionIdstring uuid required

The session ID (UUID) returned by the create endpoints and GET /sessions

Example:5ad08bfb-cbe0-4911-a8c3-309760d33029

Query parameters

include'reportBody'

Set to 'reportBody' to include the full report markdown and abstract in the response

Response

Systematic review status, available stage results, and export availability.

type'systematicReview' required
sessionIdstring uuid required

The session ID (UUID) returned by the create endpoints and GET /sessions

status'processing' | 'pausedForInsufficientQuota' | 'completed' | 'failed' | 'unknown' required

Current status. Transitions: processing ⇄ pausedForInsufficientQuota (paused when the account exceeds its usage limit; stays paused until explicitly resumed via the resume endpoint or the Elicit web interface), processing → completed/failed. Poll until completed or failed.

executionStage'gathering_sources' | 'screening_abstract' | 'screening_fulltext' | 'extracting_data' | 'generating_report' | 'done' | 'null' nullable required

Current pipeline stage. Advances through gathering_sources → screening_abstract → screening_fulltext → extracting_data → generating_report → done. Null when the stage isn't known — treat it as unknown, not as not-started.

urlstring required

URL to view the review in the Elicit web interface

isPublicboolean required

Whether the review is publicly accessible via its URL without authentication

dataFreshnessstring nullable required

ISO timestamp of the cached export manifest used for this response, or null when no timestamp is available for the returned data. An unchanged timestamp can indicate a stale cache; the timestamp alone does not guarantee that every completed stage is exported.

exportsStatus'ready' | 'generating' | 'unavailable' required

Availability of cached export download URLs in data. ready: a cached manifest was served; it can be stale, including during regeneration or failures, and does not guarantee a complete current export set. If expected URLs are missing, repoll after at least 60 seconds with bounded backoff, even after completion. generating: exports are being generated and no cached downloads can be served. unavailable: export generation or retrieval failed and no cached downloads can be served; structured report content may still be available.

Example response

{
  "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
  "links": {
    "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029",
    "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume"
  }
}

Changes