Exa Research API

openapi: 3.2.0
info:
  title: Exa Research API
  version: 2.0.0
  description: Exa Research API - subset of the Exa Public API.
servers:
- url: https://api.exa.ai
security:
- apiKey: []
- bearer: []
tags:
- name: Research
paths:
  /research/v1:
    get:
      description: Get a paginated list of research requests
      operationId: ResearchController_listResearch
      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:
      - Research
      x-codeSamples:
      - lang: bash
        label: List research tasks
        source: "curl -X GET 'https://api.exa.ai/research/v1?limit=10' \\\n  -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(api_key=''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);'
    post:
      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'
      summary: Create a new research request
      tags:
      - Research
      x-codeSamples:
      - lang: bash
        label: Create research task
        source: "curl -X POST 'https://api.exa.ai/research/v1' \\\n  -H 'x-api-key: YOUR-EXA-API-KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"instructions\": \"Summarize the latest developments in AI safety research\",\n    \"model\": \"exa-research\"\n  }'"
      - lang: python
        label: Create research task
        source: "# pip install exa-py\nfrom exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\ntask = exa.research.create_task(\n    instructions=\"Summarize the latest developments in AI safety research\",\n    model=\"exa-research\"\n)\n\nprint(task)"
      - lang: javascript
        label: Create research task
        source: "// npm install exa-js\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst task = await exa.research.createTask({\n  instructions: \"Summarize the latest developments in AI safety research\",\n  model: \"exa-research\"\n});\n\nconsole.log(task);"
  /research/v1/{researchId}:
    get:
      description: Retrieve research by ID. Add ?stream=true for real-time SSE updates.
      operationId: ResearchController_getResearch
      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:
      - Research
      x-codeSamples:
      - lang: bash
        label: Get research task
        source: "curl -X GET 'https://api.exa.ai/research/v1/01jszdfs0052sg4jc552sg4jc5' \\\n  -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' \\\n  -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(api_key=''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);'
components:
  schemas:
    ListResearchResponseDto:
      type:
      - object
      properties:
        data:
          type:
          - array
          items:
            discriminator:
              propertyName: status
            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
            $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
    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
                    - keyword
                    - auto
                    - fast
                    description: Search algorithm used (neural for semantic search, keyword for exact matches)
                  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
                    - keyword
                    - auto
                    - fast
                    description: Search algorithm used (neural for semantic search, keyword for exact matches)
                  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
    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
          citations:
            type:
            - array
            items:
              type:
              - object
              properties:
                id:
                  type:
                  - string
                url:
                  type:
                  - string
                publishedDate:
                  type:
                  - string
                author:
                  type:
                  - string
                  - 'null'
                score:
                  type:
                  - number
                text:
                  type:
                  - string
                highlights:
                  type:
                  - array
                  items:
                    type:
                    - string
                highlightScores:
                  type:
                  - array
                  items:
                    type:
                    - number
                summary:
                  type:
                  - string
                links:
                  type:
                  - array
                  items:
                    type:
                    - object
                    properties:
                      url:
                        type:
                        - string
                      text:
                        type:
                        - string
                    required:
                    - url
                    - text
                subpages:
                  type:
                  - array
                  items:
                    type:
                    - object
                    properties:
                      id:
                        type:
                        - string
                      title:
                        type:
                        - string
                      url:
                        type:
                        - string
                      publishedDate:
                        type:
                        - string
                      author:
                        type:
                        - string
                        - 'null'
                      text:
                        type:
                        - string
                      favicon:
                        type:
                        - string
                    required:
                    - id
                    - title
                    - url
                image:
                  type:
                  - string
                  - 'null'
                  description: URL of the image associated with the result
                favicon:
                  type:
                  - string
                  - 'null'
                  description: URL of the favicon associated with the result
                description:
                  type:
                  - string
                subtitle:
                  type:
                  - string
                snippet:
                  type:
                  - string
               

# --- truncated at 32 KB (211 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/exa-ai/refs/heads/main/openapi/exa-ai-research-api-openapi.yml