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

# Execute Workflow

> Execute a workflow with an inline template definition or a stored template ID. Returns a streaming response via Server-Sent Events.



## OpenAPI

````yaml /api-rest/openapi/openapi_workflows.json post /v1/workflow/execute
openapi: 3.1.0
info:
  description: HTTP API for Bigdata Research Agent and Deep-Research capabilities
  title: Bigdata Research Agent API
  version: 1.0.0
servers:
  - description: Production server
    url: https://agents.bigdata.com
security: []
paths:
  /v1/workflow/execute:
    post:
      tags:
        - Workflows
      summary: Execute Workflow
      description: >-
        Execute a workflow with an inline template definition or a stored
        template ID. Returns a streaming response via Server-Sent Events.
      operationId: execute_workflow_v1_workflow_execute_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowExecuteRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStreamingDelta'
            text/event-stream: {}
          description: Streaming SSE response with workflow results.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - API Key Authentication: []
components:
  schemas:
    WorkflowExecuteRequest:
      description: Request to execute a workflow.
      properties:
        execution_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Provide a previous execution ID to resume a workflow conversation.
          title: Execution Id
        input:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          description: Input values for template placeholders.
          title: Input
        model_name:
          $ref: '#/components/schemas/ModelName'
          default: base
          description: >-
            Selects the model capability tier. Use "base" for the default
            routing strategy, or "pro" to allow the most capable available model
            when higher reasoning or accuracy is required. Model selection is
            dynamic and may vary based on task type, availability, and failover.
        template:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/CreateWorkflowTemplate'
          description: Template ID (string) or inline template definition (object).
          title: Template
        time_range:
          anyOf:
            - $ref: '#/components/schemas/RollingTimeRange'
            - $ref: '#/components/schemas/DateRange'
            - type: 'null'
          description: Time range filter for the workflow. Omit for unconstrained.
          title: Time Range
      required:
        - template
      title: WorkflowExecuteRequest
      type: object
    WorkflowStreamingDelta:
      description: A single streaming event from a workflow execution.
      properties:
        delta:
          description: The streamed message event.
          discriminator:
            mapping:
              ACTION:
                $ref: '#/components/schemas/ActionMessage'
              ANSWER:
                $ref: '#/components/schemas/AnswerMessage'
              AUDIT:
                $ref: '#/components/schemas/AuditMessage'
              CHART:
                $ref: '#/components/schemas/ChartMessage'
              COMPLETE:
                $ref: '#/components/schemas/CompleteMessage'
              ERROR:
                $ref: '#/components/schemas/ErrorMessage'
              GROUNDING:
                $ref: '#/components/schemas/GroundingMessage'
              LLM_RETRY:
                $ref: '#/components/schemas/LlmRetryMessage'
              PLANNING:
                $ref: '#/components/schemas/PlanningMessage'
              STRUCTURED_OUTPUT:
                $ref: '#/components/schemas/StructuredOutputMessage'
              THINKING:
                $ref: '#/components/schemas/ThinkingMessage'
              TOOL_ERROR:
                $ref: '#/components/schemas/ToolErrorMessage'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/ThinkingMessage'
            - $ref: '#/components/schemas/ActionMessage'
            - $ref: '#/components/schemas/AnswerMessage'
            - $ref: '#/components/schemas/CompleteMessage'
            - $ref: '#/components/schemas/ErrorMessage'
            - $ref: '#/components/schemas/AuditMessage'
            - $ref: '#/components/schemas/GroundingMessage'
            - $ref: '#/components/schemas/ChartMessage'
            - $ref: '#/components/schemas/ToolErrorMessage'
            - $ref: '#/components/schemas/PlanningMessage'
            - $ref: '#/components/schemas/LlmRetryMessage'
            - $ref: '#/components/schemas/StructuredOutputMessage'
          title: Delta
        execution_id:
          description: >-
            Workflow conversation identifier. Use this to resume the
            conversation.
          title: Execution Id
          type: string
        request_id:
          description: Unique identifier for this request.
          title: Request Id
          type: string
      required:
        - request_id
        - execution_id
        - delta
      title: WorkflowStreamingDelta
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ModelName:
      description: Available models for execution.
      enum:
        - base
        - pro
      title: ModelName
      type: string
    CreateWorkflowTemplate:
      description: Inline workflow template definition.
      properties:
        content_filter:
          anyOf:
            - $ref: '#/components/schemas/ContentFilter'
            - type: 'null'
          description: Content filters applied to all searches.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Brief description of what this template does.
          title: Description
        expected_input:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/WorkflowInputSchema'
              type: object
            - type: 'null'
          description: >-
            Inputs the template expects. Each key is an abstract snake_case
            NAME, not a value. Reference a key as {{ key }} in the prompt to
            substitute its value inline; an unreferenced key is still provided
            to the model as attached context.
          title: Expected Input
        expected_output:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          description: >-
            Optional guidance for the final answer's tone, structure, and
            format.
          title: Expected Output
        name:
          description: Template display name.
          title: Name
          type: string
        prompt:
          description: The research prompt with optional placeholders.
          title: Prompt
          type: string
        ranking_parameters:
          anyOf:
            - $ref: '#/components/schemas/RankingParameters'
            - type: 'null'
          description: Search result ranking configuration.
        research_plan:
          anyOf:
            - $ref: '#/components/schemas/Plan'
            - type: 'null'
          description: Pre-defined research plan for the workflow.
        tools_configs:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Per-tool configuration stored with the template, keyed by tool id.
            Two key families are supported: `python_code_execution` (toggles
            sandboxed Python and chart rendering for every run) and connector
            tool ids in the `<connector>__<tool>` form (e.g.
            `"factset__FactSet_Fundamentals": {"enabled": true}`). Search
            settings belong in `content_filter`, `ranking_parameters`, or the
            execution request — not here. See `GET /v1/tools` for each connector
            tool's config schema.
          examples:
            - factset__FactSet_Fundamentals:
                enabled: true
              python_code_execution:
                chart_generation_enabled: false
                enabled: true
          title: Tools Configs
      required:
        - name
        - prompt
      title: CreateWorkflowTemplate
      type: object
    RollingTimeRange:
      description: Predefined rolling time windows for filtering data.
      enum:
        - last_24_hours
        - last_7_days
        - last_30_days
        - last_60_days
        - last_90_days
        - last_180_days
        - last_365_days
      title: RollingTimeRange
      type: string
    DateRange:
      description: Absolute time range for filtering content.
      properties:
        end:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: End of the time range (ISO 8601 UTC, e.g. '2024-12-31T23:59:59Z').
          title: End
        start:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Start of the time range (ISO 8601 UTC, e.g. '2024-01-01T00:00:00Z').
          title: Start
      title: DateRange
      type: object
    ActionMessage:
      description: Notification that the agent is invoking a tool.
      properties:
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        tool_arguments:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Arguments passed to the tool.
          title: Tool Arguments
        tool_name:
          description: Name of the tool being called.
          title: Tool Name
          type: string
        type:
          const: ACTION
          default: ACTION
          title: Type
          type: string
      required:
        - tool_name
      title: ActionMessage
      type: object
    AnswerMessage:
      description: A chunk of the agent's final answer text.
      properties:
        content:
          description: Answer text content.
          title: Content
          type: string
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: ANSWER
          default: ANSWER
          title: Type
          type: string
      required:
        - content
      title: AnswerMessage
      type: object
    AuditMessage:
      description: Detailed trace data from tool executions.
      properties:
        audit_traces:
          description: Audit traces from tool executions.
          items:
            anyOf:
              - $ref: '#/components/schemas/SearchAuditV1'
              - $ref: '#/components/schemas/MarkdownAuditV1'
              - $ref: '#/components/schemas/StructuredReportAuditV1'
              - $ref: '#/components/schemas/SubAgentStartedAuditV1'
              - $ref: '#/components/schemas/SubAgentCompletedAuditV1'
          title: Audit Traces
          type: array
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: AUDIT
          default: AUDIT
          title: Type
          type: string
      required:
        - audit_traces
      title: AuditMessage
      type: object
    ChartMessage:
      description: A chart the agent produced while running code.
      properties:
        caption:
          description: Short description of the chart.
          title: Caption
          type: string
        chart_id:
          description: Unique identifier for the chart.
          title: Chart Id
          type: string
        chart_type:
          description: Chart shape, e.g. 'bar', 'line', 'scatter', 'area', or 'histogram'.
          title: Chart Type
          type: string
        data_points:
          anyOf:
            - type: integer
            - type: 'null'
          description: Number of data points plotted in the chart.
          title: Data Points
        end:
          description: End offset in the cumulative answer text (exclusive).
          title: End
          type: integer
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        start:
          description: Start offset in the cumulative answer text.
          title: Start
          type: integer
        title:
          description: Chart title.
          title: Title
          type: string
        type:
          const: CHART
          default: CHART
          title: Type
          type: string
        vega_lite_spec:
          additionalProperties: true
          description: >-
            A standard Vega-Lite specification for the chart. Render it with any
            Vega-Lite renderer: https://vega.github.io/vega-lite/docs/
          title: Vega Lite Spec
          type: object
      required:
        - chart_id
        - title
        - caption
        - chart_type
        - vega_lite_spec
        - start
        - end
      title: ChartMessage
      type: object
    CompleteMessage:
      description: Signals that the agent has finished processing the request.
      properties:
        checkpoint_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Checkpoint for continuing this conversation.
          title: Checkpoint Id
        consumption:
          description: Resource usage breakdown for this request.
          items:
            discriminator:
              mapping:
                base:
                  $ref: '#/components/schemas/TokenTierConsumption'
                pro:
                  $ref: '#/components/schemas/TokenTierConsumption'
                search:
                  $ref: '#/components/schemas/SearchConsumption'
                search_endpoint:
                  $ref: '#/components/schemas/SearchEndpointConsumption'
                structured_data:
                  $ref: '#/components/schemas/StructuredDataConsumption'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/TokenTierConsumption'
              - $ref: '#/components/schemas/SearchConsumption'
              - $ref: '#/components/schemas/StructuredDataConsumption'
              - $ref: '#/components/schemas/SearchEndpointConsumption'
          title: Consumption
          type: array
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: COMPLETE
          default: COMPLETE
          title: Type
          type: string
      required:
        - consumption
      title: CompleteMessage
      type: object
    ErrorMessage:
      description: An unrecoverable error during processing.
      properties:
        error:
          description: Error description.
          title: Error
          type: string
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: ERROR
          default: ERROR
          title: Type
          type: string
      required:
        - error
      title: ErrorMessage
      type: object
    GroundingMessage:
      description: Citations linking answer text spans to their sources.
      properties:
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        references:
          description: Source references for spans of the answer text.
          items:
            $ref: '#/components/schemas/GroundingReference'
          title: References
          type: array
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: GROUNDING
          default: GROUNDING
          title: Type
          type: string
      required:
        - references
      title: GroundingMessage
      type: object
    LlmRetryMessage:
      description: Notification that the agent is retrying a failed operation.
      properties:
        message:
          description: Human-readable retry status.
          title: Message
          type: string
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: LLM_RETRY
          default: LLM_RETRY
          title: Type
          type: string
      required:
        - message
      title: LlmRetryMessage
      type: object
    PlanningMessage:
      description: Updates to the agent's research plan.
      properties:
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        plan:
          $ref: '#/components/schemas/Plan'
          description: Current state of the research plan.
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: PLANNING
          default: PLANNING
          title: Type
          type: string
      required:
        - plan
      title: PlanningMessage
      type: object
    StructuredOutputMessage:
      description: Structured data extracted from the research results.
      properties:
        content:
          anyOf:
            - additionalProperties: true
              type: object
            - items: {}
              type: array
          description: Extracted structured data matching the requested schema.
          title: Content
        json_schema:
          additionalProperties: true
          description: The JSON Schema used to produce this output.
          title: Json Schema
          type: object
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: STRUCTURED_OUTPUT
          default: STRUCTURED_OUTPUT
          title: Type
          type: string
      required:
        - json_schema
        - content
      title: StructuredOutputMessage
      type: object
    ThinkingMessage:
      description: The agent's intermediate reasoning while researching.
      properties:
        content:
          description: The agent's reasoning text.
          title: Content
          type: string
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        type:
          const: THINKING
          default: THINKING
          title: Type
          type: string
      required:
        - content
      title: ThinkingMessage
      type: object
    ToolErrorMessage:
      description: A recoverable error from a specific tool.
      properties:
        error:
          description: Error description.
          title: Error
          type: string
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Groups related message chunks that belong to the same logical unit.
          title: Message Id
        role:
          default: assistant
          description: >-
            Message source: 'assistant' for the main agent, or a sub-agent role
            name.
          title: Role
          type: string
        tool_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Name of the tool that encountered the error.
          title: Tool Name
        type:
          const: TOOL_ERROR
          default: TOOL_ERROR
          title: Type
          type: string
      required:
        - error
      title: ToolErrorMessage
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    ContentFilter:
      description: Composable content filter using logical operators.
      properties:
        all_of:
          description: Match content satisfying all of these filters.
          items:
            discriminator:
              mapping:
                DOCUMENT_ID:
                  $ref: '#/components/schemas/DocumentIdFilter'
                SOURCE_TYPE:
                  $ref: '#/components/schemas/SourceFilter'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/DocumentIdFilter'
              - $ref: '#/components/schemas/SourceFilter'
          title: All Of
          type: array
        any_of:
          description: Match content satisfying at least one of these filters.
          items:
            discriminator:
              mapping:
                DOCUMENT_ID:
                  $ref: '#/components/schemas/DocumentIdFilter'
                SOURCE_TYPE:
                  $ref: '#/components/schemas/SourceFilter'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/DocumentIdFilter'
              - $ref: '#/components/schemas/SourceFilter'
          title: Any Of
          type: array
        none_of:
          description: Exclude content matching any of these filters.
          items:
            discriminator:
              mapping:
                DOCUMENT_ID:
                  $ref: '#/components/schemas/DocumentIdFilter'
                SOURCE_TYPE:
                  $ref: '#/components/schemas/SourceFilter'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/DocumentIdFilter'
              - $ref: '#/components/schemas/SourceFilter'
          title: None Of
          type: array
      title: ContentFilter
      type: object
    WorkflowInputSchema:
      description: Defines an input placeholder in a workflow template.
      properties:
        type:
          $ref: '#/components/schemas/WorkflowInputTypes'
          description: Expected input type for this placeholder.
      required:
        - type
      title: WorkflowInputSchema
      type: object
    RankingParameters:
      description: Parameters that influence how search results are ranked.
      properties:
        freshness_boost:
          anyOf:
            - maximum: 10
              minimum: 1
              type: integer
            - type: 'null'
          description: Prioritize more recent content (1-10).
          title: Freshness Boost
        source_boost:
          anyOf:
            - maximum: 10
              minimum: 1
              type: integer
            - type: 'null'
          description: Boost results from high-quality, authoritative sources (1-10).
          title: Source Boost
      title: RankingParameters
      type: object
    Plan:
      description: A structured research plan with ordered steps.
      properties:
        steps:
          default: []
          description: Ordered list of research steps.
          items:
            $ref: '#/components/schemas/Step'
          title: Steps
          type: array
        title:
          description: Short title summarizing the research objective.
          title: Title
          type: string
      required:
        - title
      title: Plan
      type: object
    SearchAuditV1:
      description: Audit trace for a search operation.
      properties:
        audit_type:
          const: SearchAuditV1
          default: SearchAuditV1
          title: Audit Type
          type: string
        query:
          $ref: '#/components/schemas/TraceQuery'
          description: The query that was executed.
        results:
          description: Search results grouped by source type.
          items:
            anyOf:
              - $ref: '#/components/schemas/AuditTraceBigdataResult'
              - $ref: '#/components/schemas/AuditTraceExternalResult'
          title: Results
          type: array
        tool_id:
          description: Identifier of the tool that produced this trace.
          title: Tool Id
          type: string
      required:
        - tool_id
        - query
        - results
      title: SearchAuditV1
      type: object
    MarkdownAuditV1:
      description: Audit trace for generated markdown content.
      properties:
        audit_type:
          const: MarkdownAuditV1
          default: MarkdownAuditV1
          title: Audit Type
          type: string
        content:
          description: The generated markdown content.
          title: Content
          type: string
        title:
          description: Title of the generated content.
          title: Title
          type: string
        tool_id:
          description: Identifier of the tool that produced this trace.
          title: Tool Id
          type: string
      required:
        - tool_id
        - title
        - content
      title: MarkdownAuditV1
      type: object
    StructuredReportAuditV1:
      description: Audit trace for a structured data report.
      properties:
        audit_type:
          const: StructuredReportAuditV1
          default: StructuredReportAuditV1
          title: Audit Type
          type: string
        structured_report:
          $ref: '#/components/schemas/StructuredReport'
          description: The generated structured report.
        tool_id:
          description: Identifier of the tool that produced this trace.
          title: Tool Id
          type: string
      required:
        - tool_id
        - structured_report
      title: StructuredReportAuditV1
      type: object
    SubAgentStartedAuditV1:
      description: Audit trace emitted when a sub-agent begins its research task.
      properties:
        agent_role:
          description: Role name of the sub-agent.
          title: Agent Role
          type: string
        audit_type:
          const: SubAgentStartedAuditV1
          default: SubAgentStartedAuditV1
          title: Audit Type
          type: string
        plan:
          anyOf:
            - $ref: '#/components/schemas/Plan'
            - type: 'null'
          description: The sub-agent's research plan, if available.
        plan_title:
          description: Title of the sub-agent's research plan.
          title: Plan Title
          type: string
        step_index:
          description: Index of the plan step this sub-agent is executing.
          title: Step Index
          type: integer
        tool_id:
          description: Identifier of the tool that produced this trace.
          title: Tool Id
          type: string
      required:
        - tool_id
        - agent_role
        - plan_title
        - step_index
      title: SubAgentStartedAuditV1
      type: object
    SubAgentCompletedAuditV1:
      description: Audit trace emitted when a sub-agent finishes its research task.
      properties:
        audit_type:
          const: SubAgentCompletedAuditV1
          default: SubAgentCompletedAuditV1
          title: Audit Type
          type: string
        consumption:
          description: Resource usage for this sub-agent's execution.
          items:
            discriminator:
              mapping:
                base:
                  $ref: '#/components/schemas/TokenTierConsumption'
                pro:
                  $ref: '#/components/schemas/TokenTierConsumption'
                search:
                  $ref: '#/components/schemas/SearchConsumption'
                search_endpoint:
                  $ref: '#/components/schemas/SearchEndpointConsumption'
                structured_data:
                  $ref: '#/components/schemas/StructuredDataConsumption'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/TokenTierConsumption'
              - $ref: '#/components/schemas/SearchConsumption'
              - $ref: '#/components/schemas/StructuredDataConsumption'
              - $ref: '#/components/schemas/SearchEndpointConsumption'
          title: Consumption
          type: array
        success:
          description: Whether the sub-agent completed successfully.
          title: Success
          type: boolean
        tool_id:
          description: Identifier of the tool that produced this trace.
          title: Tool Id
          type: string
      required:
        - tool_id
        - success
      title: SubAgentCompletedAuditV1
      type: object
    TokenTierConsumption:
      description: Token usage for a specific model tier.
      properties:
        cached_tokens:
          default: 0
          description: Number of tokens served from cache.
          title: Cached Tokens
          type: integer
        input_tokens:
          description: Number of input tokens consumed.
          title: Input Tokens
          type: integer
        output_tokens:
          description: Number of output tokens generated.
          title: Output Tokens
          type: integer
        type:
          description: Model tier this consumption applies to.
          enum:
            - base
            - pro
          title: Type
          type: string
      required:
        - type
        - input_tokens
        - output_tokens
      title: TokenTierConsumption
      type: object
    SearchConsumption:
      description: Search tokens consumed against a content tier.
      properties:
        content_tier:
          description: Content tier the search ran against.
          title: Content Tier
          type: string
        mode:
          const: fast
          default: fast
          description: Search mode the tokens were consumed in.
          title: Mode
          type: string
        tokens_count:
          description: Number of search tokens consumed.
          title: Tokens Count
          type: integer
        type:
          const: search
          default: search
          title: Type
          type: string
      required:
        - content_tier
        - tokens_count
      title: SearchConsumption
      type: object
    SearchEndpointConsumption:
      description: Search tokens consumed against a specific search endpoint.
      properties:
        endpoint:
          description: Search endpoint the tokens were consumed against.
          enum:
            - comentions
            - volume
            - knowledge-graph
          title: Endpoint
          type: string
        tokens_count:
          description: Number of search tokens consumed.
          title: Tokens Count
          type: integer
        type:
          const: search_endpoint
          default: search_endpoint
          title: Type
          type: string
      required:
        - endpoint
        - tokens_count
      title: SearchEndpointConsumption
      type: object
    StructuredDataConsumption:
      description: Structured-data tokens consumed against a content tier.
      properties:
        content_tier:
          description: Content tier the structured-data read ran against.
          title: Content Tier
          type: string
        tokens_count:
          description: Number of structured-data tokens consumed.
          title: Tokens Count
          type: integer
        type:
          const: structured_data
          default: structured_data
          title: Type
          type: string
      required:
        - content_tier
        - tokens_count
      title: StructuredDataConsumption
      type: object
    GroundingReference:
      description: A citation linking a span of answer text to its source.
      properties:
        audit_id:
          description: Identifier linking this reference to its audit trace.
          title: Audit Id
          type: string
        end:
          description: End character offset (exclusive) in the answer text.
          title: End
          type: integer
        source:
          anyOf:
            - discriminator:
                mapping:
                  BIGDATA:
                    $ref: '#/components/schemas/BigdataDocument'
                  EXTERNAL:
                    $ref: '#/components/schemas/ExternalResult'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/ExternalResult'
                - $ref: '#/components/schemas/BigdataDocument'
            - type: 'null'
          description: The referenced source document or web result.
          title: Source
        start:
          description: Start character offset in the answer text.
          title: Start
          type: integer
        tool_name:
          description: Name of the tool that produced this reference.
          title: Tool Name
          type: string
      required:
        - start
        - end
        - tool_name
        - audit_id
      title: GroundingReference
      type: object
    DocumentIdFilter:
      description: Filter by specific document identifiers.
      properties:
        document_ids:
          description: Set of document IDs to match.
          items:
            type: string
          maxItems: 1000
          minItems: 1
          title: Document Ids
          type: array
          uniqueItems: true
        type:
          const: DOCUMENT_ID
          description: Filter type identifier.
          title: Type
          type: string
      required:
        - type
        - document_ids
      title: DocumentIdFilter
      type: object
    SourceFilter:
      description: Filter by content source identifiers.
      properties:
        sources_ids:
          description: Set of source IDs to match.
          items:
            type: string
          maxItems: 1000
          minItems: 1
          title: Sources Ids
          type: array
          uniqueItems: true
        type:
          const: SOURCE_TYPE
          description: Filter type identifier.
          title: Type
          type: string
      required:
        - type
        - sources_ids
      title: SourceFilter
      type: object
    WorkflowInputTypes:
      description: Supported input types for workflow template placeholders.
      enum:
        - rp_entity_id
        - string
      title: WorkflowInputTypes
      type: string
    Step:
      description: A single step within a research plan.
      properties:
        description:
          description: What this step will investigate or produce.
          title: Description
          type: string
        status:
          $ref: '#/components/schemas/StepStatus'
          default: NOT_STARTED
          description: Current status of this step.
      required:
        - description
      title: Step
      type: object
    TraceQuery:
      description: A search query executed by the agent.
      properties:
        text:
          description: The search query text.
          title: Text
          type: string
      required:
        - text
      title: TraceQuery
      type: object
    AuditTraceBigdataResult:
      description: Search results from the Bigdata content platform.
      properties:
        type:
          const: CQS
          default: CQS
          description: Result type identifier.
          title: Type
          type: string
        values:
          description: Matching documents.
          items:
            $ref: '#/components/schemas/BigdataDocument'
          title: Values
          type: array
      required:
        - values
      title: AuditTraceBigdataResult
      type: object
    AuditTraceExternalResult:
      description: Search results from external web sources.
      properties:
        type:
          const: EXTERNAL
          default: EXTERNAL
          description: Result type identifier.
          title: Type
          type: string
        values:
          description: Matching external results.
          items:
            $ref: '#/components/schemas/ExternalResult'
          title: Values
          type: array
      required:
        - values
      title: AuditTraceExternalResult
      type: object
    StructuredReport:
      description: A structured report with multiple sections.
      properties:
        components:
          description: Report sections.
          items:
            $ref: '#/components/schemas/ReportComponent'
          title: Components
          type: array
        title:
          description: Report title.
          title: Title
          type: string
      required:
        - title
      title: StructuredReport
      type: object
    BigdataDocument:
      description: A document from the Bigdata content platform.
      properties:
        chunks:
          anyOf:
            - items:
                $ref: '#/components/schemas/BigdataChunk'
              type: array
            - type: 'null'
          description: Text chunks with matched content.
          title: Chunks
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          description: Content type classification.
          title: Content Type
        document_scope:
          anyOf:
            - type: string
            - type: 'null'
          description: Scope or section of the document.
          title: Document Scope
        document_type:
          anyOf:
            - type: string
            - type: 'null'
          description: Document type classification.
          title: Document Type
        hd:
          description: Document headline or title.
          title: Hd
          type: string
        id:
          description: Unique document identifier.
          title: Id
          type: string
        language:
          description: Document language code.
          title: Language
          type: string
        rp_provider_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Provider identifier.
          title: Rp Provider Id
        source_rank:
          description: Ranking weight of the source.
          title: Source Rank
          type: integer
        src_key:
          description: Source key identifier.
          title: Src Key
          type: string
        src_name:
          description: Source display name.
          title: Src Name
          type: string
        ts:
          description: Publication timestamp.
          title: Ts
          type: string
        type:
          const: BIGDATA
          default: BIGDATA
          description: Source type identifier.
          title: Type
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          description: URL of the original document.
          title: Url
      required:
        - hd
        - id
        - language
        - src_key
        - src_name
        - source_rank
        - ts
      title: BigdataDocument
      type: object
    ExternalResult:
      description: A result from an external web source.
      properties:
        action:
          $ref: '#/components/schemas/ExternalSourceAction'
          description: Source metadata and URL.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Brief summary.
          title: Description
        hd:
          description: Headline or title.
          title: Hd
          type: string
        id:
          description: Unique identifier for this result.
          title: Id
          type: string
        text:
          description: Content text excerpt.
          title: Text
          type: string
        ts:
          anyOf:
            - type: string
            - type: 'null'
          description: Publication timestamp.
          title: Ts
        type:
          const: EXTERNAL
          default: EXTERNAL
          description: Source type identifier.
          title: Type
          type: string
      required:
        - id
        - hd
        - text
        - action
      title: ExternalResult
      type: object
    StepStatus:
      description: Status of a research plan step.
      enum:
        - NOT_STARTED
        - IN_PROGRESS
        - COMPLETED
        - SKIPPED
        - FAILED
      title: StepStatus
      type: string
    ReportComponent:
      description: A section of a structured report.
      properties:
        blocks:
          description: Content blocks within this section.
          items:
            anyOf:
              - $ref: '#/components/schemas/HeaderBlock'
              - $ref: '#/components/schemas/TextBlock'
              - $ref: '#/components/schemas/StructuredBlock'
          title: Blocks
          type: array
        component_type:
          $ref: '#/components/schemas/ComponentType'
          description: Type of report section.
        title:
          description: Section title.
          title: Title
          type: string
      required:
        - component_type
        - title
      title: ReportComponent
      type: object
    BigdataChunk:
      description: A text chunk from a Bigdata document.
      properties:
        bounding_boxes:
          anyOf:
            - items:
                $ref: '#/components/schemas/BoundingBox'
              type: array
            - type: 'null'
          description: Spatial positions for PDF-sourced content.
          title: Bounding Boxes
        cnum:
          description: Chunk number within the document.
          title: Cnum
          type: integer
        id:
          description: Chunk identifier.
          title: Id
          type: string
        sentences:
          description: Sentence positions within this chunk.
          items:
            $ref: '#/components/schemas/ChunkSentence'
          title: Sentences
          type: array
        text:
          description: Chunk text content.
          title: Text
          type: string
      required:
        - id
        - cnum
        - text
        - sentences
      title: BigdataChunk
      type: object
    ExternalSourceAction:
      description: Metadata for an external web source.
      properties:
        favicon_url:
          anyOf:
            - type: string
            - type: 'null'
          description: URL of the source's favicon.
          title: Favicon Url
        hd:
          description: Headline or title.
          title: Hd
          type: string
        name:
          description: Display name of the source.
          title: Name
          type: string
        type:
          const: EXTERNAL
          default: EXTERNAL
          description: Source type identifier.
          title: Type
          type: string
        url:
          description: URL of the original content.
          title: Url
          type: string
      required:
        - name
        - hd
        - url
      title: ExternalSourceAction
      type: object
    HeaderBlock:
      description: A heading block within a report section.
      properties:
        block_type:
          const: header
          default: header
          description: Block type identifier.
          title: Block Type
          type: string
        level:
          default: 2
          description: Heading level (1-6).
          maximum: 6
          minimum: 1
          title: Level
          type: integer
        text:
          description: Heading text.
          minLength: 1
          title: Text
          type: string
      required:
        - text
      title: HeaderBlock
      type: object
    TextBlock:
      description: A plain text block within a report section.
      properties:
        block_type:
          const: text
          default: text
          description: Block type identifier.
          title: Block Type
          type: string
        content:
          description: Text content.
          title: Content
          type: string
      required:
        - content
      title: TextBlock
      type: object
    StructuredBlock:
      description: A structured data block (e.g., table) within a report section.
      properties:
        block_type:
          const: structured
          default: structured
          description: Block type identifier.
          title: Block Type
          type: string
        structured_type:
          $ref: '#/components/schemas/StructuredType'
          default: table
          description: Type of structured data.
        table:
          $ref: '#/components/schemas/DataTable'
          description: Table data.
      required:
        - table
      title: StructuredBlock
      type: object
    ComponentType:
      description: Types of structured report components.
      enum:
        - company_overview
        - key_financial_highlights
        - analyst_data
        - forward_estimates
        - price_performance
        - latest_earnings
        - financial_data
        - additional_financial_metrics
        - revenue_segmentation
        - earnings_calendar
      title: ComponentType
      type: string
    BoundingBox:
      description: Spatial coordinates of content on a document page.
      properties:
        bottom:
          title: Bottom
          type: number
        left:
          title: Left
          type: number
        page:
          title: Page
          type: integer
        right:
          title: Right
          type: number
        top:
          title: Top
          type: number
      required:
        - bottom
        - left
        - page
        - right
        - top
      title: BoundingBox
      type: object
    ChunkSentence:
      description: Position reference within a document chunk.
      properties:
        pnum:
          description: Paragraph number.
          title: Pnum
          type: integer
        snum:
          description: Sentence number within the paragraph.
          title: Snum
          type: integer
      required:
        - pnum
        - snum
      title: ChunkSentence
      type: object
    StructuredType:
      description: Types of structured data blocks.
      enum:
        - table
      title: StructuredType
      type: string
    DataTable:
      description: A table of structured data.
      properties:
        caption:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional table description.
          title: Caption
        headers:
          description: Column header names.
          items:
            type: string
          minItems: 1
          title: Headers
          type: array
        rows:
          description: Row data as key-value mappings.
          items:
            additionalProperties: true
            type: object
          title: Rows
          type: array
      required:
        - headers
      title: DataTable
      type: object
  securitySchemes:
    API Key Authentication:
      description: API key for authentication.
      in: header
      name: X-API-Key
      type: apiKey

````