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

# Create a new report

`POST /sessions/reports`

## Request

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

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 while `status` is `processing`. If it becomes `pausedForInsufficientQuota`, resolve the usage limit and POST to `links.resume` before continuing.
3. When complete, use the available `pdfUrl` and `docxUrl` fields to download the report, and `txtUrl`, `bibUrl`, and `risUrl` for its reference list (APA text, BibTeX, and RIS). Check `exportsStatus` for reference-list availability; these URLs are not guaranteed to be present immediately.

### 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 while status is "processing"; resolve quota pauses before resuming
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. Only the owner can use it; a shared recipient receives 404 even when this link is present.

## 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. 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`: API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `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/reports/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)