3.1.00.0.1The Elicit API provides programmatic access to Elicit's research capabilities, including semantic search over 125 million+ academic papers and automated report generation.
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer elk_live_your_key_here
API keys can be created and managed from your Elicit account settings.
There is no extra charge for API access. Reports created via the API count against your workflow quota, the same as reports created through the web interface. Search requests are rate-limited based on your plan tier — see the Search endpoint for details.
Manage your plan in account settings.
Working examples in curl, Python, and JavaScript, plus integrations (CLI tool, Slack bot, Claude Code skill):
github.com/elicit/api-examples
All errors return a consistent JSON structure with an error object containing a machine-readable code and a human-readable message.
https://elicit.comPOST/api/v1/searchSearch Elicit's database of over 125 million academic papers using natural language queries.
Semantic search uses natural language understanding to find relevant papers even when the exact terms don't match.
| Plan | Papers per request | Requests per day |
|---|---|---|
| Basic | 100 | 20 |
| Plus | 100 | 100 |
| Pro | 1,000 | 1,000 |
| Team | 1,000 | No limit |
| Enterprise | 5,000 | No limit |
Upgrade your plan in account settings for higher limits.
curl -X POST https://elicit.com/api/v1/search \
-H "Authorization: Bearer elk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"query": "effects of sleep deprivation on cognitive performance"}'
query (required)string — The search query string
filtersobject — Filters to narrow search results
excludeKeywordsarray — Keywords to exclude from results
string
hasPdfboolean — Only include papers with available PDFs
includeKeywordsarray — Keywords that must appear in the paper
string
maxEpochSinteger — Maximum publication date as Unix epoch seconds
maxQuartileinteger — Maximum journal quartile (1 = top 25%)
maxYearinteger — Maximum publication year
minEpochSinteger — Minimum publication date as Unix epoch seconds
minYearinteger — Minimum publication year
pubmedOnlyboolean — Only include papers from PubMed
retractedstring, possible values: "exclude_retracted", "include_retracted", "only_retracted" — How to handle retracted papers. Defaults to exclude_retracted.
typeTagsarray — Filter by study type
string, possible values: "Review", "Meta-Analysis", "Systematic Review", "RCT", "Longitudinal"
maxResultsinteger, default: 10 — Maximum number of results to return (1-5000)
Example:
{
"query": "GLP-1 receptor agonists for weight loss",
"filters": {
"minYear": 2020,
"maxYear": 2025,
"minEpochS": 1672531200,
"maxEpochS": 1772505448,
"maxQuartile": 2,
"includeKeywords": [
"semaglutide",
"liraglutide"
],
"excludeKeywords": [
"rodent",
"mouse model"
],
"typeTags": [
"RCT",
"Meta-Analysis"
],
"hasPdf": false,
"pubmedOnly": false,
"retracted": "exclude_retracted"
},
"maxResults": 10
}papers (required)array — List of papers matching the query
abstract (required)string | null — Paper abstract
authors (required)array — List of author names
string
citedByCount (required)integer | null — Number of citations this paper has received
doi (required)string | null — Digital Object Identifier
elicitId (required)string | null — Elicit internal paper identifier
pmid (required)string | null — PubMed identifier
title (required)string — Paper title
urls (required)array — URLs for the paper
string
venue (required)string | null — Publication venue
year (required)integer | null — Publication year
Example:
{
"papers": [
{
"elicitId": null,
"title": "",
"authors": [
""
],
"year": null,
"abstract": null,
"doi": null,
"pmid": null,
"venue": null,
"citedByCount": null,
"urls": [
""
]
}
]
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}POST/api/v1/reportsStart 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 reportId that you use to poll for status via GET /api/v1/reports/:reportId.
The report is also visible at the url returned in the response, where you can watch it progress in real time.
reportId)status is completed or failedpdfUrl and docxUrl fields on the completed response to download the report# 1. Create the report
curl -X POST https://elicit.com/api/v1/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/v1/reports/{reportId} \
-H "Authorization: Bearer elk_live_your_key_here"
researchQuestion (required)string — The research question to investigate. Elicit will search for relevant papers, screen them, and extract data to produce a structured report.
maxExtractPapersinteger, default: 10 — Maximum number of papers to include in the final extraction table. Papers are screened for relevance before extraction. Defaults to 10.
maxSearchPapersinteger, default: 50 — Maximum number of papers to retrieve during the search phase. More papers means a more comprehensive but slower report. Defaults to 50.
Example:
{
"researchQuestion": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?",
"maxSearchPapers": 50,
"maxExtractPapers": 10
}reportId (required)string — Unique identifier for the report. Use this to poll for status.
status (required)string — Initial status is always processing
url (required)string — URL to view the report in the Elicit web interface as it progresses
Example:
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}GET/api/v1/reportsList all reports for the authenticated user, ordered by creation date (newest first).
Results are paginated using cursor-based pagination. Use the nextCursor value from the response to fetch the next page.
# First page
curl https://elicit.com/api/v1/reports?limit=10 \
-H "Authorization: Bearer elk_live_your_key_here"
# Next page
curl "https://elicit.com/api/v1/reports?limit=10&cursor=2025-06-15T14:30:00.000Z" \
-H "Authorization: Bearer elk_live_your_key_here"
# Filter to API-created reports only
curl https://elicit.com/api/v1/reports?source=api \
-H "Authorization: Bearer elk_live_your_key_here"
nextCursor (required)string | null — Cursor for the next page of results. Null if there are no more results.
reports (required)array — List of reports
createdAt (required)string — ISO 8601 timestamp of when the report was created
reportId (required)string — Unique identifier for the report
source (required)string, possible values: "api", "user" — How the report was created
status (required)string, possible values: "processing", "completed", "failed", "unknown" — Current status of the report
title (required)string — Report title (the research question)
url (required)string — URL to view the report in the Elicit web interface
Example:
{
"reports": [
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"title": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029",
"source": "api",
"createdAt": "2025-06-15T14:30:00.000Z"
}
],
"nextCursor": "2025-06-15T14:30:00.000Z"
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}GET/api/v1/reports/{reportId}Poll the status of a report created via POST /api/v1/reports.
url.result field contains the report content.error field contains details.Poll every 30–60 seconds. Reports typically complete in 5–15 minutes depending on the number of papers.
By default, the reportBody and abstract fields are omitted to keep polling responses lightweight. To include them, add ?include=reportBody to the request.
# Poll for status
curl https://elicit.com/api/v1/reports/{reportId} \
-H "Authorization: Bearer elk_live_your_key_here"
# Fetch with full report body
curl "https://elicit.com/api/v1/reports/{reportId}?include=reportBody" \
-H "Authorization: Bearer elk_live_your_key_here"
reportId (required)string — Unique identifier for the report
status (required)string, possible values: "processing", "completed", "failed", "unknown" — Current status of the report. Transitions: processing → completed/failed. Poll until completed or failed.
url (required)string — URL to view the report in the Elicit web interface
docxUrlstring | null — Pre-signed URL to download the report as DOCX. Only present when status is completed and assets have been generated. Expires after 7 days — re-fetch the report for a fresh URL.
errorobject — Error details, only present when status is failed
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
pdfUrlstring | null — Pre-signed URL to download the report as PDF. Only present when status is completed and assets have been generated. Expires after 7 days — re-fetch the report for a fresh URL.
resultobject — Report output, only present when status is completed
summary (required)string — AI-generated executive summary of the findings
title (required)string — Auto-generated title for the report
abstractstring | null — Report abstract in markdown format. Only included when ?include=reportBody is specified.
reportBodystring | null — Full report content in markdown format. Only included when ?include=reportBody is specified.
Example:
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029",
"result": {
"title": "GLP-1 Receptor Agonists and Cardiovascular Outcomes: A Systematic Review",
"summary": "This review analyzed 42 studies examining the cardiovascular effects of GLP-1 receptor agonists. The evidence suggests significant reductions in major adverse cardiovascular events (MACE), with semaglutide showing the strongest effect (HR 0.74, 95% CI 0.58-0.95)...",
"reportBody": "# Introduction\n\nGLP-1 receptor agonists have emerged as...",
"abstract": "This systematic review examines the cardiovascular effects of..."
},
"error": {
"code": "",
"message": ""
},
"pdfUrl": "https://s3.amazonaws.com/...",
"docxUrl": "https://s3.amazonaws.com/..."
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}error (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}objectexcludeKeywordsarray — Keywords to exclude from results
string
hasPdfboolean — Only include papers with available PDFs
includeKeywordsarray — Keywords that must appear in the paper
string
maxEpochSinteger — Maximum publication date as Unix epoch seconds
maxQuartileinteger — Maximum journal quartile (1 = top 25%)
maxYearinteger — Maximum publication year
minEpochSinteger — Minimum publication date as Unix epoch seconds
minYearinteger — Minimum publication year
pubmedOnlyboolean — Only include papers from PubMed
retractedstring, possible values: "exclude_retracted", "include_retracted", "only_retracted" — How to handle retracted papers. Defaults to exclude_retracted.
typeTagsarray — Filter by study type
string, possible values: "Review", "Meta-Analysis", "Systematic Review", "RCT", "Longitudinal"
Example:
{
"minYear": 2020,
"maxYear": 2025,
"minEpochS": 1672531200,
"maxEpochS": 1772505448,
"maxQuartile": 2,
"includeKeywords": [
"semaglutide",
"liraglutide"
],
"excludeKeywords": [
"rodent",
"mouse model"
],
"typeTags": [
"RCT",
"Meta-Analysis"
],
"hasPdf": false,
"pubmedOnly": false,
"retracted": "exclude_retracted"
}objectpapers (required)array — List of papers matching the query
abstract (required)string | null — Paper abstract
authors (required)array — List of author names
string
citedByCount (required)integer | null — Number of citations this paper has received
doi (required)string | null — Digital Object Identifier
elicitId (required)string | null — Elicit internal paper identifier
pmid (required)string | null — PubMed identifier
title (required)string — Paper title
urls (required)array — URLs for the paper
string
venue (required)string | null — Publication venue
year (required)integer | null — Publication year
Example:
{
"papers": [
{
"elicitId": null,
"title": "",
"authors": [
""
],
"year": null,
"abstract": null,
"doi": null,
"pmid": null,
"venue": null,
"citedByCount": null,
"urls": [
""
]
}
]
}objectabstract (required)string | null — Paper abstract
authors (required)array — List of author names
string
citedByCount (required)integer | null — Number of citations this paper has received
doi (required)string | null — Digital Object Identifier
elicitId (required)string | null — Elicit internal paper identifier
pmid (required)string | null — PubMed identifier
title (required)string — Paper title
urls (required)array — URLs for the paper
string
venue (required)string | null — Publication venue
year (required)integer | null — Publication year
Example:
{
"elicitId": null,
"title": "",
"authors": [
""
],
"year": null,
"abstract": null,
"doi": null,
"pmid": null,
"venue": null,
"citedByCount": null,
"urls": [
""
]
}objecterror (required)object
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
Example:
{
"error": {
"code": "invalid_request",
"message": "Invalid search request"
}
}objectreportId (required)string — Unique identifier for the report. Use this to poll for status.
status (required)string — Initial status is always processing
url (required)string — URL to view the report in the Elicit web interface as it progresses
Example:
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"
}objectnextCursor (required)string | null — Cursor for the next page of results. Null if there are no more results.
reports (required)array — List of reports
createdAt (required)string — ISO 8601 timestamp of when the report was created
reportId (required)string — Unique identifier for the report
source (required)string, possible values: "api", "user" — How the report was created
status (required)string, possible values: "processing", "completed", "failed", "unknown" — Current status of the report
title (required)string — Report title (the research question)
url (required)string — URL to view the report in the Elicit web interface
Example:
{
"reports": [
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"title": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029",
"source": "api",
"createdAt": "2025-06-15T14:30:00.000Z"
}
],
"nextCursor": "2025-06-15T14:30:00.000Z"
}objectcreatedAt (required)string — ISO 8601 timestamp of when the report was created
reportId (required)string — Unique identifier for the report
source (required)string, possible values: "api", "user" — How the report was created
status (required)string, possible values: "processing", "completed", "failed", "unknown" — Current status of the report
title (required)string — Report title (the research question)
url (required)string — URL to view the report in the Elicit web interface
Example:
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"title": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029",
"source": "api",
"createdAt": "2025-06-15T14:30:00.000Z"
}objectreportId (required)string — Unique identifier for the report
status (required)string, possible values: "processing", "completed", "failed", "unknown" — Current status of the report. Transitions: processing → completed/failed. Poll until completed or failed.
url (required)string — URL to view the report in the Elicit web interface
docxUrlstring | null — Pre-signed URL to download the report as DOCX. Only present when status is completed and assets have been generated. Expires after 7 days — re-fetch the report for a fresh URL.
errorobject — Error details, only present when status is failed
code (required)string — Machine-readable error code
message (required)string — Human-readable error message
pdfUrlstring | null — Pre-signed URL to download the report as PDF. Only present when status is completed and assets have been generated. Expires after 7 days — re-fetch the report for a fresh URL.
resultobject — Report output, only present when status is completed
summary (required)string — AI-generated executive summary of the findings
title (required)string — Auto-generated title for the report
abstractstring | null — Report abstract in markdown format. Only included when ?include=reportBody is specified.
reportBodystring | null — Full report content in markdown format. Only included when ?include=reportBody is specified.
Example:
{
"reportId": "5ad08bfb-cbe0-4911-a8c3-309760d33029",
"status": "processing",
"url": "https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029",
"result": {
"title": "GLP-1 Receptor Agonists and Cardiovascular Outcomes: A Systematic Review",
"summary": "This review analyzed 42 studies examining the cardiovascular effects of GLP-1 receptor agonists. The evidence suggests significant reductions in major adverse cardiovascular events (MACE), with semaglutide showing the strongest effect (HR 0.74, 95% CI 0.58-0.95)...",
"reportBody": "# Introduction\n\nGLP-1 receptor agonists have emerged as...",
"abstract": "This systematic review examines the cardiovascular effects of..."
},
"error": {
"code": "",
"message": ""
},
"pdfUrl": "https://s3.amazonaws.com/...",
"docxUrl": "https://s3.amazonaws.com/..."
}objectsummary (required)string — AI-generated executive summary of the findings
title (required)string — Auto-generated title for the report
abstractstring | null — Report abstract in markdown format. Only included when ?include=reportBody is specified.
reportBodystring | null — Full report content in markdown format. Only included when ?include=reportBody is specified.
Example:
{
"title": "GLP-1 Receptor Agonists and Cardiovascular Outcomes: A Systematic Review",
"summary": "This review analyzed 42 studies examining the cardiovascular effects of GLP-1 receptor agonists. The evidence suggests significant reductions in major adverse cardiovascular events (MACE), with semaglutide showing the strongest effect (HR 0.74, 95% CI 0.58-0.95)...",
"reportBody": "# Introduction\n\nGLP-1 receptor agonists have emerged as...",
"abstract": "This systematic review examines the cardiovascular effects of..."
}