> ## Documentation Index
> Fetch the complete documentation index at: https://exa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a task
> Create an asynchronous research task that explores the web, gathers sources, synthesizes findings, and returns results with citations. Can be used to generate:
1. Structured JSON matching an `outputSchema` you provide.
2. A detailed markdown report when no schema is provided.
The API responds immediately with a `researchId` for polling completion status. For more details, see the [Research API overview](/reference/research/overview).
Alternatively, you can use the OpenAI compatible [chat completions interface](/reference/chat-completions#research).
The Research API (`/research/v1`) is being deprecated on **May 1, 2026**. Migrate to [`/search`](/reference/search) with `type: "deep-reasoning"` for equivalent functionality. See the [deprecation notice](/changelog/may-2026-api-deprecations) for details.
## OpenAPI
````yaml post /research/v1
openapi: 3.1.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: {}
servers:
- url: https://api.exa.ai
description: Production
security:
- api_key: []
tags: []
paths:
/research/v1:
post:
tags:
- Research
summary: Create a new research request
operationId: ResearchController_createResearch
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'
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);
components:
schemas:
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:
- 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
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
securitySchemes:
api_key:
type: apiKey
in: header
name: x-api-key
description: Your Exa API key
````