openapi: 3.1.0 paths: /research/v1: get: description: Get a paginated list of research requests operationId: ResearchController_listResearch x-codeSamples: - lang: bash label: List research tasks source: | curl -X GET 'https://api.exa.ai/research/v1?limit=10' \ -H 'x-api-key: YOUR-EXA-API-KEY' - lang: python label: List research tasks source: | # pip install exa-py from exa_py import Exa exa = Exa('YOUR_EXA_API_KEY') tasks = exa.research.list_tasks(limit=10) print(tasks) - lang: javascript label: List research tasks source: | // npm install exa-js import Exa from 'exa-js'; const exa = new Exa('YOUR_EXA_API_KEY'); const tasks = await exa.research.listTasks({ limit: 10 }); console.log(tasks); parameters: - name: cursor required: false in: query description: The cursor to paginate through the results schema: minLength: 1 type: string - name: limit required: false in: query description: Number of results per page (1-50) schema: minimum: 1 maximum: 50 default: 10 type: number responses: '200': description: List of research requests content: application/json: schema: $ref: '#/components/schemas/ListResearchResponseDto' summary: List research requests tags: &ref_0 - Research post: operationId: ResearchController_createResearch x-codeSamples: - lang: bash label: Create research task source: | curl -X POST 'https://api.exa.ai/research/v1' \ -H 'x-api-key: YOUR-EXA-API-KEY' \ -H 'Content-Type: application/json' \ -d '{ "instructions": "Summarize the latest developments in AI safety research", "model": "exa-research" }' - lang: python label: Create research task source: | # pip install exa-py from exa_py import Exa exa = Exa('YOUR_EXA_API_KEY') task = exa.research.create_task( instructions="Summarize the latest developments in AI safety research", model="exa-research" ) print(task) - lang: javascript label: Create research task source: | // npm install exa-js import Exa from 'exa-js'; const exa = new Exa('YOUR_EXA_API_KEY'); const task = await exa.research.createTask({ instructions: "Summarize the latest developments in AI safety research", model: "exa-research" }); console.log(task); parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResearchCreateRequestDtoClass' responses: '201': description: Research request created content: application/json: schema: $ref: '#/components/schemas/ResearchDtoClass' summary: Create a new research request tags: *ref_0 /research/v1/{researchId}: get: description: Retrieve research by ID. Add ?stream=true for real-time SSE updates. operationId: ResearchController_getResearch x-codeSamples: - lang: bash label: Get research task source: > curl -X GET 'https://api.exa.ai/research/v1/01jszdfs0052sg4jc552sg4jc5' \ -H 'x-api-key: YOUR-EXA-API-KEY' - lang: bash label: Get research task with streaming source: > curl -X GET 'https://api.exa.ai/research/v1/01jszdfs0052sg4jc552sg4jc5?stream=true' \ -H 'x-api-key: YOUR-EXA-API-KEY' - lang: python label: Get research task source: | # pip install exa-py from exa_py import Exa exa = Exa('YOUR_EXA_API_KEY') task = exa.research.get_task('01jszdfs0052sg4jc552sg4jc5') print(task) - lang: javascript label: Get research task source: > // npm install exa-js import Exa from 'exa-js'; const exa = new Exa('YOUR_EXA_API_KEY'); const task = await exa.research.getTask('01jszdfs0052sg4jc552sg4jc5'); console.log(task); parameters: - name: researchId required: true in: path description: The unique identifier of the research request to retrieve schema: type: string - name: stream required: false in: query description: >- Set to "true" to receive real-time updates via Server-Sent Events (SSE) schema: type: string - name: events required: false in: query description: >- Set to "true" to include the detailed event log of all operations performed schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ResearchDtoClass' summary: Get a research request by id tags: *ref_0 info: title: Exa Research API description: >- Create asynchronous research tasks that explore the web, gather sources, synthesize findings, and return structured results with citations. Perfect for complex, multi-step research that requires reasoning over web data. version: 1.0.0 contact: {} tags: [] servers: - url: https://api.exa.ai description: Production security: - api_key: [] components: securitySchemes: api_key: type: apiKey in: header name: x-api-key description: Your Exa API key schemas: ListResearchResponseDto: type: - object properties: data: type: - array items: discriminator: propertyName: status examples: &ref_1 - researchId: 01jszdfs0052sg4jc552sg4jc5 model: exa-research instructions: What species of ant are similar to honeypot ants? status: running - researchId: 01jszdfs0052sg4jc552sg4jc5 model: exa-research instructions: What species of ant are similar to honeypot ants? status: completed output: Melophorus bagoti $ref: '#/components/schemas/ResearchDtoClass' description: Research requests ordered by creation time (newest first) hasMore: type: - boolean description: If true, use nextCursor to fetch more results nextCursor: type: - string - 'null' description: Pass this value as the cursor parameter to fetch the next page required: - data - hasMore - nextCursor ResearchCreateRequestDtoClass: type: - object properties: model: default: exa-research type: - string enum: - exa-research-fast - exa-research - exa-research-pro description: >- Research model to use. exa-research is faster and cheaper, while exa-research-pro provides more thorough analysis and stronger reasoning. instructions: type: - string maxLength: 4096 description: >- Instructions for what you would like research on. A good prompt clearly defines what information you want to find, how research should be conducted, and what the output should look like. outputSchema: type: - object additionalProperties: {} description: >- JSON Schema to enforce structured output. When provided, the research output will be validated against this schema and returned as parsed JSON. required: - instructions examples: - model: exa-research instructions: What species of ant are similar to honeypot ants? ResearchDtoClass: discriminator: propertyName: status oneOf: - type: - object properties: researchId: type: - string description: >- Unique identifier for tracking and retrieving this research request createdAt: type: - number description: When the research was created (Unix timestamp in milliseconds) model: default: exa-research type: - string enum: - exa-research-fast - exa-research - exa-research-pro description: The model used for this research request instructions: type: - string description: The original research instructions provided outputSchema: type: - object additionalProperties: {} description: The JSON Schema used to validate the output, if provided status: type: - string enum: - pending required: - researchId - createdAt - instructions - status title: Pending - type: - object properties: researchId: type: - string description: >- Unique identifier for tracking and retrieving this research request createdAt: type: - number description: When the research was created (Unix timestamp in milliseconds) model: default: exa-research type: - string enum: - exa-research-fast - exa-research - exa-research-pro description: The model used for this research request instructions: type: - string description: The original research instructions provided outputSchema: type: - object additionalProperties: {} description: The JSON Schema used to validate the output, if provided status: type: - string enum: - running events: type: - array items: $ref: '#/components/schemas/ResearchEventDtoClass' description: >- Real-time log of operations as research progresses. Poll this endpoint or use ?stream=true for live updates. required: - researchId - createdAt - instructions - status title: Running - type: - object properties: researchId: type: - string description: >- Unique identifier for tracking and retrieving this research request createdAt: type: - number description: When the research was created (Unix timestamp in milliseconds) model: default: exa-research type: - string enum: - exa-research-fast - exa-research - exa-research-pro description: The model used for this research request instructions: type: - string description: The original research instructions provided outputSchema: type: - object additionalProperties: {} description: The JSON Schema used to validate the output, if provided status: type: - string enum: - completed events: type: - array items: $ref: '#/components/schemas/ResearchEventDtoClass' description: >- Detailed log of all operations performed during research. Use ?events=true to include this field for debugging or monitoring progress. output: type: - object properties: content: type: - string description: >- The complete research output as text. If outputSchema was provided, this is a JSON string. parsed: type: - object additionalProperties: {} description: >- Structured JSON object matching your outputSchema. Only present when outputSchema was provided and the output successfully validated. required: - content description: >- The final research results, containing both raw text and parsed JSON if outputSchema was provided costDollars: type: - object properties: total: type: - number description: Total cost in USD for this research request numSearches: type: - number description: >- Count of web searches performed. Each search query counts as one search. numPages: type: - number description: >- Count of web pages fully crawled and processed. Only pages that were read in detail are counted. reasoningTokens: type: - number description: >- Total AI tokens used for reasoning, planning, and generating the final output required: - total - numSearches - numPages - reasoningTokens description: Detailed cost breakdown for billing purposes finishedAt: type: - number description: When the research completed (Unix timestamp in milliseconds) required: - researchId - createdAt - instructions - status - output - costDollars - finishedAt title: Completed - type: - object properties: researchId: type: - string description: >- Unique identifier for tracking and retrieving this research request createdAt: type: - number description: When the research was created (Unix timestamp in milliseconds) model: default: exa-research type: - string enum: - exa-research-fast - exa-research - exa-research-pro description: The model used for this research request instructions: type: - string description: The original research instructions provided outputSchema: type: - object additionalProperties: {} description: The JSON Schema used to validate the output, if provided status: type: - string enum: - canceled events: type: - array items: $ref: '#/components/schemas/ResearchEventDtoClass' description: >- Detailed log of all operations performed during research. Use ?events=true to include this field for debugging or monitoring progress. finishedAt: type: - number description: When the research was canceled (Unix timestamp in milliseconds) required: - researchId - createdAt - instructions - status - finishedAt title: Canceled - type: - object properties: researchId: type: - string description: >- Unique identifier for tracking and retrieving this research request createdAt: type: - number description: When the research was created (Unix timestamp in milliseconds) model: default: exa-research type: - string enum: - exa-research-fast - exa-research - exa-research-pro description: The model used for this research request instructions: type: - string description: The original research instructions provided outputSchema: type: - object additionalProperties: {} description: The JSON Schema used to validate the output, if provided status: type: - string enum: - failed events: type: - array items: $ref: '#/components/schemas/ResearchEventDtoClass' description: >- Detailed log of all operations performed during research. Use ?events=true to include this field for debugging or monitoring progress. error: type: - string description: Human-readable error message explaining what went wrong. finishedAt: type: - number description: When the research failed (Unix timestamp in milliseconds) required: - researchId - createdAt - instructions - status - error - finishedAt title: Failed examples: *ref_1 ResearchOperationDtoClass: discriminator: propertyName: type oneOf: - type: - object properties: type: type: - string enum: - think content: type: - string description: The AI's reasoning process and decision-making steps required: - type - content title: Think - type: - object properties: type: type: - string enum: - search searchType: type: - string enum: - neural - auto - fast description: >- Search algorithm used (neural for semantic search, auto for intelligent search method selection) goal: type: - string description: What the AI is trying to find with this search query: type: - string description: The exact search query sent to the search engine results: type: - array items: type: - object properties: url: type: - string required: - url description: URLs returned by the search, ranked by relevance pageTokens: type: - number description: Token cost for processing search result snippets required: - type - searchType - query - results - pageTokens title: Search - type: - object properties: type: type: - string enum: - crawl goal: type: - string description: What information the AI expects to find on this page result: type: - object properties: url: type: - string required: - url description: The specific page that was crawled pageTokens: type: - number description: Token cost for processing the full page content required: - type - result - pageTokens title: Crawl ResearchEventDtoClass: oneOf: - discriminator: propertyName: eventType oneOf: - type: - object properties: eventType: type: - string enum: - research-definition instructions: type: - string description: The complete research instructions as provided outputSchema: type: - object additionalProperties: {} description: The JSON Schema that will validate the final output createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - instructions - createdAt - researchId title: Research Definition - type: - object properties: eventType: type: - string enum: - research-output output: discriminator: propertyName: outputType oneOf: - type: - object properties: outputType: type: - string enum: - completed costDollars: type: - object properties: total: type: - number description: Total cost in USD for this research request numSearches: type: - number description: >- Count of web searches performed. Each search query counts as one search. numPages: type: - number description: >- Count of web pages fully crawled and processed. Only pages that were read in detail are counted. reasoningTokens: type: - number description: >- Total AI tokens used for reasoning, planning, and generating the final output required: - total - numSearches - numPages - reasoningTokens content: type: - string description: >- The complete research output as text. If outputSchema was provided, this is a JSON string. parsed: type: - object additionalProperties: {} description: >- Structured JSON object matching your outputSchema. Only present when outputSchema was provided and the output successfully validated. required: - outputType - costDollars - content title: Completed - type: - object properties: outputType: type: - string enum: - failed error: type: - string description: >- Detailed error message explaining why the research failed required: - outputType - error title: Failed description: >- The final research result, either successful with data or failed with error createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - output - createdAt - researchId title: Research Output - discriminator: propertyName: eventType oneOf: - type: - object properties: eventType: type: - string enum: - plan-definition planId: type: - string description: Identifier for this planning cycle createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - planId - createdAt - researchId title: Plan Definition - type: - object properties: eventType: type: - string enum: - plan-operation planId: type: - string description: Which plan this operation belongs to operationId: type: - string description: Unique identifier for this specific operation data: discriminator: propertyName: type oneOf: - type: - object properties: type: type: - string enum: - think content: type: - string description: The AI's reasoning process and decision-making steps required: - type - content title: Think - type: - object properties: type: type: - string enum: - search searchType: type: - string enum: - neural - auto - fast description: >- Search algorithm used (neural for semantic search, auto for intelligent search method selection) goal: type: - string description: What the AI is trying to find with this search query: type: - string description: The exact search query sent to the search engine results: type: - array items: type: - object properties: url: type: - string required: - url description: URLs returned by the search, ranked by relevance pageTokens: type: - number description: Token cost for processing search result snippets required: - type - searchType - query - results - pageTokens title: Search - type: - object properties: type: type: - string enum: - crawl goal: type: - string description: What information the AI expects to find on this page result: type: - object properties: url: type: - string required: - url description: The specific page that was crawled pageTokens: type: - number description: Token cost for processing the full page content required: - type - result - pageTokens title: Crawl description: The actual operation performed (think, search, or crawl) createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - planId - operationId - data - createdAt - researchId title: Plan Operation - type: - object properties: eventType: type: - string enum: - plan-output planId: type: - string description: Which plan is producing this output output: discriminator: propertyName: outputType oneOf: - type: - object properties: outputType: type: - string enum: - tasks reasoning: type: - string description: Why these specific tasks were chosen tasksInstructions: type: - array items: type: - string description: >- List of task instructions that will be executed in parallel required: - outputType - reasoning - tasksInstructions title: Tasks - type: - object properties: outputType: type: - string enum: - stop reasoning: type: - string description: Why the AI decided to stop researching required: - outputType - reasoning title: Stop description: >- The plan's decision: either generate tasks or stop researching createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - planId - output - createdAt - researchId title: Plan Output - discriminator: propertyName: eventType oneOf: - type: - object properties: eventType: type: - string enum: - task-definition planId: type: - string description: The plan that generated this task taskId: type: - string description: Identifier for tracking this specific task instructions: type: - string description: What this task should accomplish createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - planId - taskId - instructions - createdAt - researchId title: Task Definition - type: - object properties: eventType: type: - string enum: - task-operation planId: type: - string description: The plan that owns this task taskId: type: - string description: Which task is performing this operation operationId: type: - string description: Unique identifier for this specific operation data: discriminator: propertyName: type oneOf: - type: - object properties: type: type: - string enum: - think content: type: - string description: The AI's reasoning process and decision-making steps required: - type - content title: Think - type: - object properties: type: type: - string enum: - search searchType: type: - string enum: - neural - auto - fast description: >- Search algorithm used (neural for semantic search, auto for intelligent search method selection) goal: type: - string description: What the AI is trying to find with this search query: type: - string description: The exact search query sent to the search engine results: type: - array items: type: - object properties: url: type: - string required: - url description: URLs returned by the search, ranked by relevance pageTokens: type: - number description: Token cost for processing search result snippets required: - type - searchType - query - results - pageTokens title: Search - type: - object properties: type: type: - string enum: - crawl goal: type: - string description: What information the AI expects to find on this page result: type: - object properties: url: type: - string required: - url description: The specific page that was crawled pageTokens: type: - number description: Token cost for processing the full page content required: - type - result - pageTokens title: Crawl description: The actual operation performed within this task createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - planId - taskId - operationId - data - createdAt - researchId title: Task Operation - type: - object properties: eventType: type: - string enum: - task-output planId: type: - string description: The plan that owns this task taskId: type: - string description: Which task produced this output output: type: - object properties: outputType: type: - string enum: - completed content: type: - string description: The information gathered by this task required: - outputType - content description: The successful completion result of this task createdAt: type: - number description: When this event occurred (Unix timestamp in milliseconds) researchId: type: - string description: The research request this event belongs to required: - eventType - planId - taskId - output - createdAt - researchId title: Task Output