---
title: "Create a new report"
method: POST
path: "/sessions/reports"
tags: ["Reports"]
---

# Create a new report

`POST /sessions/reports`

Start an asynchronous report generation job. Elicit will search for relevant papers, screen them for relevance, extract structured data, and produce a full research report.

Reports are long-running operations (typically 5–15 minutes). The response includes a `sessionId` and a `links.self` URL that you poll for status.

The report is also visible at the `url` returned in the response, where you can watch it progress in real time.

### Workflow

1. **POST /api/v2/sessions/reports** — submit your research question (returns immediately with `sessionId`)
2. **GET `links.self`** (`/api/v2/sessions/reports/:sessionId`) — poll until `status` is `completed` or `failed`
3. Use the `pdfUrl` and `docxUrl` fields on the completed response to download the report, and `txtUrl`, `bibUrl`, and `risUrl` to download its reference list (APA text, BibTeX, and RIS)

### Example

```bash
# 1. Create the report
curl -X POST https://elicit.com/api/v2/sessions/reports \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"researchQuestion": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"}'

# 2. Poll for completion (repeat until status is "completed" or "failed")
curl https://elicit.com/api/v2/sessions/reports/{sessionId} \
  -H "Authorization: Bearer elk_live_your_key_here"
```

## Request body

- object
  - `researchQuestion` string, required — The research question to investigate. Elicit will search for relevant papers, screen them, and extract data to produce a structured report.
  - `title` string — Optional title for the report. If provided, Elicit will use this as the report title instead of generating one automatically from the research question.
  - `maxSearchPapers` integer — Maximum number of papers to retrieve during the search phase. More papers means a more comprehensive but slower report. Defaults to 50.
  - `maxExtractPapers` integer — Maximum number of papers to include in the final extraction table. Papers are screened for relevance before extraction. Defaults to 10.
  - `isPublic` boolean — Whether the report should be publicly accessible via its URL without authentication. Defaults to false.

## Response `202`

Report creation accepted. The report is now being generated asynchronously. Poll `links.self` for status.

- ReportSessionCreated
  - `type` 'report', 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 report in the Elicit web interface as it progresses
  - `isPublic` boolean, required — Whether the report 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 `researchQuestion` is present and within length limits.
- `401` — Authentication failed. The API key is missing, invalid, revoked, or expired.
- `402` — Insufficient quota.
- `403` — API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `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)