> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Research Job

> Kick off a Dex Research job.

Persists a ``research`` job and starts :class:`~dex_api.temporal.research.workflows.research_workflow.ResearchWorkflow`
on the research task queue.

**Scope:** one ``inputs.vector_stores`` id, **or** one or more ``inputs.parse_results`` ids
(no mixing with vector stores). **Empty inputs:** if the project has exactly one vector store,
that store is used automatically (empty-input shortcut).



## OpenAPI

````yaml https://dex.sgp.scale.com/openapi.json post /v1/projects/{project_id}/research
openapi: 3.1.0
info:
  title: Document Understanding API
  description: API for uploading and processing documents
  version: 0.4.5
servers: []
security:
  - ApiKey: []
    AccountId: []
tags:
  - name: Projects
    description: Operations related to project creation and management
  - name: Files
    description: Operations related to file upload and access
  - name: Parse
    description: Operations related to starting parse jobs and accessing their results
  - name: Vector Stores
    description: Operations related to vector store creation and management
  - name: Extract
    description: Operations related to starting extract jobs and accessing their results
  - name: Research
    description: Dex Research agent kickoff and results.
  - name: Jobs
    description: Operations related to monitoring jobs and their status
paths:
  /v1/projects/{project_id}/research:
    post:
      tags:
        - Research
      summary: Create Research Job
      description: >-
        Kick off a Dex Research job.


        Persists a ``research`` job and starts
        :class:`~dex_api.temporal.research.workflows.research_workflow.ResearchWorkflow`

        on the research task queue.


        **Scope:** one ``inputs.vector_stores`` id, **or** one or more
        ``inputs.parse_results`` ids

        (no mixing with vector stores). **Empty inputs:** if the project has
        exactly one vector store,

        that store is used automatically (empty-input shortcut).
      operationId: create_research_job_v1_projects__project_id__research_post
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchJobRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobEntity'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ResearchJobRequest:
      properties:
        inputs:
          $ref: '#/components/schemas/ResearchInputs'
          description: >-
            Explicit scope. Empty lists: the API resolves to the project's
            **sole** vector store when exactly one exists; otherwise set
            vector_stores or parse_results explicitly.
        task:
          $ref: '#/components/schemas/ResearchTask'
        tools:
          additionalProperties:
            $ref: '#/components/schemas/ResearchToolConfigEntry'
          type: object
          title: Tools
          description: Map tool name → enablement + config
        model:
          type: string
          title: Model
          description: Default model for all agent steps unless overridden in advanced
        advanced:
          anyOf:
            - $ref: '#/components/schemas/ResearchAdvanced'
            - type: 'null'
          description: Per-stage model/prompt/temperature/reasoning overrides
        execute_dependent_subtask_tool_hints:
          type: boolean
          title: Execute Dependent Subtask Tool Hints
          description: >-
            When True, DECOMPOSE tool hints for dependent subtasks are executed
            as warm-start searches (same semantics as extract
            ``execute_dependent_subtask_tool_hints``). Default False
            (intent-only hints for dependents).
          default: false
      additionalProperties: false
      type: object
      required:
        - task
        - model
      title: ResearchJobRequest
      description: >-
        Kickoff body for ``POST /v1/projects/{project_id}/research``.


        Use ``tools`` for per-tool enablement and configuration (same map shape
        as

        :class:`~dex_core.models.extraction.ExtractionParameters.agentic_tools`
        on extract jobs).
      example:
        advanced:
          decomposition:
            model: openai/gpt-5.4
            prompt: PROMPT_DECOMPOSITION
            reasoning:
              effort: high
            temperature: 0
          subtasks:
            model: openai/gpt-5.3-codex
            prompt: PROMPT_SUBTASKS
            temperature: 0
        inputs:
          parse_results:
            - pres_9f86d081884c7d659a2feaa0c55ad015
          vector_stores:
            - vector_store_9f86d081884c7d659a2feaa0c55ad015
        model: openai/gpt-5.4
        task:
          description: What is the Commencement Date of the document?
          output_schema:
            properties:
              commencement_date:
                description: The Commencement Date
                type: string
            type: object
          plan: |-
            1. Find the Start Date
            2. Search for Commencement Date
        tools:
          lexical_search:
            config: {}
            enabled: false
          similarity_search:
            config:
              filters:
                file_id:
                  $eq: file_9f86d081884c7d659a2feaa0c55ad015
              top_k: 5
            enabled: true
    JobEntity:
      properties:
        id:
          type: string
          title: Id
          description: ID of the entity
        project_id:
          type: string
          title: Project Id
          description: ID of the project
        object:
          type: string
          const: job
          title: Object
          default: job
        operation:
          $ref: '#/components/schemas/JobOperationType'
          description: Operation type (e.g., 'parse')
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current job status
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
          description: Source document/file ID
        correlation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Correlation Id
          description: Request correlation ID for tracing
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the job was created
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: When the job started processing
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: When the job completed
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
          description: Job result payload when completed
        progress:
          anyOf:
            - $ref: '#/components/schemas/BatchParseProgress'
            - type: 'null'
          description: Live progress payload (used by batch jobs)
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if job failed
        history:
          anyOf:
            - items:
                $ref: '#/components/schemas/JobHistoryEvent'
              type: array
            - type: 'null'
          title: History
          description: Timeline of job execution events
      type: object
      required:
        - id
        - project_id
        - operation
        - status
        - created_at
      title: JobEntity
      description: Job response model representing an asynchronous operation.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResearchInputs:
      properties:
        files:
          items:
            type: string
          type: array
          title: Files
          description: Uploaded file IDs (e.g. file_…) — not yet supported.
        parse_results:
          items:
            type: string
          type: array
          title: Parse Results
          description: Parse result IDs (e.g. pres_…)
        vector_stores:
          items:
            type: string
          type: array
          title: Vector Stores
          description: Vector store IDs to search
        indexes:
          items:
            type: string
          type: array
          title: Indexes
          description: >-
            Index IDs (at most one). Enables index-based search/navigation
            tools.
      type: object
      title: ResearchInputs
      description: >-
        Scoped inputs for a research job. If all are empty, the API resolves to
        the project's sole vector store.
    ResearchTask:
      properties:
        description:
          type: string
          title: Description
          description: Goal of the research / extraction task
        plan:
          anyOf:
            - type: string
            - type: 'null'
          title: Plan
          description: Unstructured plan or guidance for the agent
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
          description: JSON Schema for structured output
        report_schema:
          anyOf:
            - type: string
            - type: 'null'
          title: Report Schema
          description: Unstructured template (e.g. markdown) for report-style output
      type: object
      required:
        - description
      title: ResearchTask
      description: 'User task: goal, optional plan, and structured or report-shaped output.'
    ResearchToolConfigEntry:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: When False, the tool is not offered to the agent
          default: true
        config:
          additionalProperties: true
          type: object
          title: Config
          description: Tool-specific configuration (e.g. top_k, filters, rerank_config)
      type: object
      title: ResearchToolConfigEntry
      description: >-
        Per-tool enablement and opaque config (e.g. search_config for
        similarity_search).
    ResearchAdvanced:
      properties:
        decomposition:
          anyOf:
            - $ref: '#/components/schemas/ResearchDecompositionAdvanced'
            - type: 'null'
          description: >-
            Decomposition step overrides (model, prompt, rules, temperature,
            reasoning)
        subtasks:
          anyOf:
            - $ref: '#/components/schemas/ResearchSubtaskAdvancedSettings'
            - type: 'null'
          description: Subtask / ReAct step overrides including max_cycles
        aggregation:
          anyOf:
            - $ref: '#/components/schemas/ResearchAdvancedStep'
            - type: 'null'
          description: Aggregation step overrides (model, prompt, temperature, reasoning)
        output_validation:
          anyOf:
            - $ref: '#/components/schemas/ResearchOutputValidationAdvanced'
            - type: 'null'
          description: Output validation / schema-fix loop overrides including max_cycles
      type: object
      title: ResearchAdvanced
      description: Optional per-stage overrides (``advanced`` object).
    JobOperationType:
      type: string
      enum:
        - parse
        - batch_parse
        - extract
        - research
        - vector_store
        - chunk
        - summarization
        - create_index
        - update_index
      title: JobOperationType
      description: Enum for job operation values.
    JobStatus:
      type: string
      enum:
        - pending
        - running
        - succeeded
        - partially_succeeded
        - failed
        - cancelled
      title: JobStatus
      description: Enum for job status values.
    BatchParseProgress:
      properties:
        total:
          type: integer
          title: Total
          description: Total number of files in the batch
        succeeded:
          type: integer
          title: Succeeded
          description: Number of successfully parsed files
        failed:
          type: integer
          title: Failed
          description: Number of files that failed to parse
        cancelled:
          type: integer
          title: Cancelled
          description: Number of cancelled child jobs
        pending:
          type: integer
          title: Pending
          description: Number of files still pending (0 when job is terminal)
        child_jobs:
          items:
            $ref: '#/components/schemas/BatchChildJobInfo'
          type: array
          title: Child Jobs
          description: Per-child job status
      type: object
      required:
        - total
        - succeeded
        - failed
        - cancelled
        - pending
        - child_jobs
      title: BatchParseProgress
      description: Live progress tracking for a batch parse job.
    JobHistoryEvent:
      properties:
        step:
          type: string
          title: Step
          description: Human-readable step name
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When this event occurred
        duration_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Ms
          description: Duration in milliseconds (for completed steps)
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Event status (e.g., 'completed', 'failed')
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: Additional event details
      type: object
      required:
        - step
        - timestamp
      title: JobHistoryEvent
      description: A single event in the job execution timeline.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ResearchDecompositionAdvanced:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ResearchReasoningBlock'
            - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
        rules:
          anyOf:
            - type: string
            - type: 'null'
          title: Rules
          description: >-
            Extra rules appended to the decompose prompt (e.g. domain-specific
            subtask guidance).
      type: object
      title: ResearchDecompositionAdvanced
      description: Decomposition step overrides (``advanced.decomposition``).
    ResearchSubtaskAdvancedSettings:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ResearchReasoningBlock'
            - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
        max_cycles:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Cycles
          description: Max ReAct iterations per subtask (default 5)
        search_rules:
          anyOf:
            - type: string
            - type: 'null'
          title: Search Rules
          description: >-
            Extra rules appended to the reasoning step search action (e.g.
            search strategy hints).
        extraction_rules:
          anyOf:
            - type: string
            - type: 'null'
          title: Extraction Rules
          description: >-
            Extra rules appended to the reasoning step extract action (e.g.
            unit/sign conventions).
      type: object
      title: ResearchSubtaskAdvancedSettings
      description: ReAct / subtask loop settings (``advanced.subtasks``).
    ResearchAdvancedStep:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ResearchReasoningBlock'
            - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
      type: object
      title: ResearchAdvancedStep
      description: Shared knobs for decomposition, subtasks, aggregation, validation.
    ResearchOutputValidationAdvanced:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ResearchReasoningBlock'
            - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
        max_cycles:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Cycles
          description: Max validation–fix cycles (default 3)
      type: object
      title: ResearchOutputValidationAdvanced
      description: Schema validation / fix loop (``advanced.output_validation``).
    BatchChildJobInfo:
      properties:
        source_document_id:
          type: string
          title: Source Document Id
          description: Source document ID
        job_id:
          type: string
          title: Job Id
          description: Child job ID
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Status of the child job
        parse_result_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parse Result Id
          description: Parse result ID if succeeded
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
      type: object
      required:
        - source_document_id
        - job_id
        - status
      title: BatchChildJobInfo
      description: Status of a single child job within a batch.
    ResearchReasoningBlock:
      properties:
        effort:
          anyOf:
            - type: string
              enum:
                - high
                - medium
                - low
                - none
            - type: 'null'
          title: Effort
          description: Model reasoning effort where applicable
      type: object
      title: ResearchReasoningBlock
      description: Nested reasoning / effort block for ``advanced.*.reasoning``.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
    AccountId:
      type: apiKey
      in: header
      name: x-selected-account-id
      description: Selected Account ID

````