{ "openapi": "3.0.1", "info": { "title": "Research Paper Search API - Academic Papers, Studies, Citations", "description": "Search 400M+ academic research papers and scientific studies with the Consensus API: filter by year, study type (RCT, meta-analysis, systematic review), field, journal quartile, sample size and citations, or ask research questions and get cited answers. Bring your own key.", "version": "0.1", "x-build-id": "Fsu4dwiimQVUaJfVv" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~academic-research-papers-search-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-academic-research-papers-search-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nabeelbaghoor~academic-research-papers-search-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-academic-research-papers-search-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nabeelbaghoor~academic-research-papers-search-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-academic-research-papers-search-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "apiKey": { "title": "Consensus API key", "type": "string", "description": "Your own Consensus API key, the value sent in the x-api-key header. Create one in the API and MCP dashboard of your Consensus account; the free plan includes 30 calls a month. Optional only when the DATA_API_KEY secret is set on the actor; otherwise the run ends with an explanation and nothing is charged." }, "mode": { "title": "What to do", "enum": [ "search", "research", "followUp", "getThread", "listThreads" ], "type": "string", "description": "Paper search returns academic papers for each query, with study filters. Research question asks the Consensus research agent and returns a cited answer. Follow-up question continues an earlier thread. Get thread reads an earlier answer by thread ID. List threads lists your earlier research threads.", "default": "search" }, "queries": { "title": "Search queries", "type": "array", "description": "Paper search only. One research question or keyword query per line, up to 50. Plain language questions work best.", "items": { "type": "string" } }, "resultsPerQuery": { "title": "Papers per query", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Paper search only. The most papers to return for each query, up to the 1,000 Consensus allows. Consensus bills one call per 100 papers, and paging past the first page needs a paid plan.", "default": 20 }, "medicalMode": { "title": "Medical mode", "type": "boolean", "description": "Paper search only. Search only top medical journals and clinical guidelines, about 8 million documents.", "default": false }, "includeSemanticScore": { "title": "Include semantic score", "type": "boolean", "description": "Paper search only. Add the relevance score to each of the top 50 papers.", "default": false }, "includeFullTextChunks": { "title": "Include full text excerpts", "type": "boolean", "description": "Paper search only. Add up to 3 query relevant full text passages per paper. Needs a paid Consensus plan (Pro, Deep, Teams or Enterprise).", "default": false }, "questions": { "title": "Research questions", "type": "array", "description": "Research question and Follow-up question. One question per line, up to 20; each starts its own research run (follow-ups are asked in order in the same thread). The agent asks nothing back, so make each one a complete brief.", "items": { "type": "string" } }, "researchBrief": { "title": "Research brief", "type": "string", "description": "Research question and Follow-up question. One longer brief of up to 10,000 characters, asked in addition to the lines above." }, "agentMode": { "title": "Agent depth", "enum": [ "pro", "deep" ], "type": "string", "description": "Research question and Follow-up question. Pro reads about 20 papers and suits almost every question. Deep reads about 50 papers, writes a structured report and needs a paid plan.", "default": "pro" }, "skill": { "title": "Research skill", "enum": [ "none", "literature-review", "citation-snowballing", "find-citations", "verify-citations" ], "type": "string", "description": "Research question and Follow-up question. Run a named research workflow instead of the agent plan. Needs agent depth Deep.", "default": "none" }, "paperIds": { "title": "Focus paper IDs", "type": "array", "description": "Research question and Follow-up question. Up to 50 Consensus paper IDs (paperId in a research answer citation) to focus the research on.", "items": { "type": "string" } }, "collectionIds": { "title": "Focus collection IDs", "type": "array", "description": "Research question and Follow-up question. Up to 10 numeric Consensus Library collection IDs to focus the research on.", "items": { "type": "string" } }, "maxWaitSeconds": { "title": "Wait for answer (seconds)", "minimum": 60, "maximum": 3600, "type": "integer", "description": "Research question and Follow-up question. How long to wait for each answer. Consensus suggests about 180 seconds for Pro and 600 for Deep. A run still going is saved as a free row with its thread ID, to collect later with Get thread.", "default": 600 }, "includeTrace": { "title": "Include agent trace", "type": "boolean", "description": "Research question, Follow-up question and Get thread. Add the plain English list of searches and papers the agent read.", "default": false }, "threadId": { "title": "Thread ID", "type": "string", "description": "Follow-up question only. The threadId of an earlier research answer, from a research row or List threads." }, "threadIds": { "title": "Thread IDs", "type": "array", "description": "Get thread only. One thread ID per line, up to 100.", "items": { "type": "string" } }, "interactionId": { "title": "Interaction ID", "type": "string", "description": "Get thread only. Read this answer of the thread instead of the latest one." }, "titleQuery": { "title": "Title contains", "type": "string", "description": "List threads only. Only threads whose title contains this text, case insensitive." }, "yearMin": { "title": "From year", "minimum": 1000, "maximum": 2100, "type": "integer", "description": "Paper search and research questions. Exclude papers published before this year." }, "yearMax": { "title": "To year", "minimum": 1000, "maximum": 2100, "type": "integer", "description": "Paper search and research questions. Exclude papers published after this year." }, "monthMin": { "title": "From month", "minimum": 1, "maximum": 12, "type": "integer", "description": "Paper search and research questions. First month within the from year (needs From year)." }, "monthMax": { "title": "To month", "minimum": 1, "maximum": 12, "type": "integer", "description": "Paper search and research questions. Last month within the to year (needs To year)." }, "studyTypes": { "title": "Study types", "type": "array", "description": "Paper search and research questions. Only include these study designs.", "items": { "type": "string", "enum": [ "rct", "meta-analysis", "systematic review", "literature review", "cohort study", "case-control study", "cross-sectional study", "longitudinal / panel data study", "non-randomized experimental study", "non-rct experimental", "non-rct observational study", "non-rct in vitro", "bench experiment", "animal", "case report", "case study", "field study", "interview study", "mixed methods study", "historical or archival analysis", "theoretical, modeling, or simulation study", "commentary or perspective", "other" ], "enumTitles": [ "Randomized controlled trial (RCT)", "Meta-analysis", "Systematic review", "Literature review", "Cohort study", "Case-control study", "Cross-sectional study", "Longitudinal / panel data study", "Non-randomized experimental study", "Non-rct experimental", "Non-rct observational study", "Non-RCT in vitro", "Bench experiment", "Animal", "Case report", "Case study", "Field study", "Interview study", "Mixed methods study", "Historical or archival analysis", "Theoretical, modeling, or simulation study", "Commentary or perspective", "Other" ] } }, "fieldsOfStudy": { "title": "Fields of study", "type": "array", "description": "Paper search and research questions. Only include these academic fields. Research questions take the first one.", "items": { "type": "string", "enum": [ "med", "bio", "cs", "chem", "psych", "phys", "mat", "eng", "env", "bus", "econ", "math", "poli", "agri", "edu", "soc", "geol", "geog", "hist", "art", "philo", "law", "ling" ], "enumTitles": [ "Medicine", "Biology", "Computer science", "Chemistry", "Psychology", "Physics", "Materials science", "Engineering", "Environmental science", "Business", "Economics", "Mathematics", "Political science", "Agriculture", "Education", "Sociology", "Geology", "Geography", "History", "Art", "Philosophy", "Law", "Linguistics" ] } }, "humanOnly": { "title": "Human studies only", "type": "boolean", "description": "Paper search and research questions.", "default": false }, "controlledOnly": { "title": "Controlled studies only", "type": "boolean", "description": "Paper search and research questions.", "default": false }, "excludePreprints": { "title": "Peer reviewed only", "type": "boolean", "description": "Paper search and research questions. Exclude preprints.", "default": false }, "openAccessOnly": { "title": "Open access only", "type": "boolean", "description": "Paper search and research questions.", "default": false }, "clinicalGuidelinesOnly": { "title": "Clinical guidelines only", "type": "boolean", "description": "Paper search and research questions. Only papers classified as clinical guidelines.", "default": false }, "sampleSizeMin": { "title": "Minimum sample size", "minimum": 1, "type": "integer", "description": "Paper search and research questions. Exclude studies with fewer participants." }, "citationMin": { "title": "Minimum citations", "minimum": 0, "type": "integer", "description": "Paper search and research questions. Exclude papers cited fewer times." }, "durationMinDays": { "title": "Minimum study duration (days)", "minimum": 0, "type": "integer", "description": "Paper search and research questions." }, "durationMaxDays": { "title": "Maximum study duration (days)", "minimum": 0, "type": "integer", "description": "Paper search and research questions." }, "journalQuartileBest": { "title": "Best journal quartile", "enum": [ "any", "1", "2", "3", "4" ], "type": "string", "description": "Paper search and research questions. SCImago journal rank: exclude journals ranked better than this quartile. Usually left at Any.", "default": "any" }, "journalQuartileWorst": { "title": "Worst journal quartile", "enum": [ "any", "1", "2", "3", "4" ], "type": "string", "description": "Paper search and research questions. SCImago journal rank: exclude journals ranked below this quartile. Q1 keeps top quartile journals only.", "default": "any" }, "countries": { "title": "Countries of study", "type": "array", "description": "Paper search and research questions. Two letter ISO 3166 codes of where the study was run, such as us, gb or de.", "items": { "type": "string" } }, "publisherNames": { "title": "Publishers", "type": "array", "description": "Paper search and research questions. Publisher display names, one per line. Research questions take the first one.", "items": { "type": "string" } }, "journalName": { "title": "Preferred journal", "type": "string", "description": "Paper search and research questions. A journal name such as Nature. Search ranks it higher without excluding other journals." }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most rows this run returns across all queries. Each row with data is charged once.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 60, "type": "integer", "description": "Pacing ceiling for calls to the Consensus API, which allows about one request a second per plan.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }