Skip to main content
This guide covers the anatomy of workflow templates and best practices for creating effective, reusable research workflows.

​
Template Anatomy

A workflow template consists of:
FieldRequiredDescription
nameYesTemplate name for identification
promptYesResearch prompt with Jinja2 placeholders
descriptionNoHuman-readable description
expected_inputNoSchema defining required inputs
content_filterNoRestrictions on searchable content
research_planNoPredefined steps for structured execution
expected_outputNoReport template describing how the final answer should look

​
Basic Template Structure

{
  "name": "Company Financial Analysis",
  "description": "Comprehensive financial analysis for any public company",
  "prompt": "Analyze {{ company_id }} from an investment perspective. Include financial metrics, competitive position, and growth outlook.",
  "expected_input": {
    "company_id": {
      "type": "rp_entity_id"
    }
  }
}

​
Input Types

​
rp_entity_id

Use for Bigdata entity identifiers (companies, ETFs, etc.): 
{
  "expected_input": {
    "company_id": {"type": "rp_entity_id"},
    "competitor_id": {"type": "rp_entity_id"}
  }
}
Entity IDs can be found using the Knowledge Graph API.

​
string

Use for free-form text input: 
{
  "expected_input": {
    "topic": {"type": "string"},
    "region": {"type": "string"}
  }
}
Example prompt using string inputs: 
Research {{ topic }} trends in the {{ region }} market.
Focus on key players, regulatory changes, and investment opportunities.

​
Content Filters

Restrict which sources the research uses:

​
Filter by Document Type

{
  "content_filter": {
    "any_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "TRANSCRIPT", "subtype": "Earnings Call"},
          {"type": "FILING"}
        ]
      }
    ]
  }
}

​
Filter by Source

{
  "content_filter": {
    "any_of": [
      {
        "type": "SOURCE_TYPE",
        "sources_ids": ["ABC123", "DEF456"]
      }
    ]
  }
}

​
Exclude Specific Content

{
  "content_filter": {
    "none_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "NEWS"}
        ]
      }
    ]
  }
}

​
Available Document Types

TypeSubtypes
TRANSCRIPTEarnings Call, General Conference Call, Investor Conference Call, etc.
TRANSCRIPT-PRESENTATIONSame subtypes as TRANSCRIPT
FILINGRNS-SEC-10-K, RNS-SEC-10-Q, RNS-SEC-8-K, etc.
NEWS(no subtypes)

​
Research Plans

Add a research plan for structured, step-by-step execution: 
{
  "research_plan": {
    "title": "Comprehensive Credit Analysis",
    "steps": [
      {"description": "Gather company background and business model"},
      {"description": "Analyze recent financial statements and leverage metrics"},
      {"description": "Review credit ratings and analyst commentary"},
      {"description": "Assess key credit risks and mitigants"},
      {"description": "Evaluate liquidity and debt maturity profile"},
      {"description": "Formulate investment recommendation"}
    ]
  }
}
When a research_plan is provided, the agent follows your predefined steps for structured, predictable output. Without a plan, the agent dynamically determines research steps based on your prompt.

​
Expected Output

The prompt controls what the agent researches. The expected_output field controls what the final report looks like: its section headings, ordering, table schemas, and tone. Setting it is the reliable way to get consistent, comparable reports across runs and across different companies. 
{
  "expected_output": "# Company Analysis\n## Executive Summary\n## Financial Overview\n| Metric | Value | YoY Change |\n| --- | --- | --- |\n## Competitive Position\n## Risks\n## Outlook"
}
Keep the two fields as separate concerns. Research instructions belong in the prompt; report structure belongs in expected_output. Mixing them is the most common cause of reports that drift in format from one run to the next.
expected_output describes the output format only, so it cannot contain {{ placeholders }}. Placeholders belong in the prompt, where they are matched against expected_input. A template with a placeholder in expected_output is rejected on create and update.
Be explicit about anything you want standardized. To force a section to always render as a table, give it a fixed column schema. To drop a recurring intro sentence, say so directly (e.g. “Present results directly, without an introductory line”). Unspecified formatting is chosen by the model per run.

​
Complete Example

Here’s a complete template for M&A transaction analysis: 
{
  "name": "M&A Transaction Analysis",
  "description": "Detailed analysis of merger or acquisition transactions",
  "prompt": "Analyze the {{ transaction_type }} involving {{ acquirer_id }} and {{ target_id }}. Include:\n\n1. Transaction overview and strategic rationale\n2. Financial terms and valuation analysis\n3. Synergy expectations and integration risks\n4. Regulatory considerations\n5. Market reaction and analyst views\n6. Impact on competitive landscape",
  "expected_input": {
    "acquirer_id": {"type": "rp_entity_id"},
    "target_id": {"type": "rp_entity_id"},
    "transaction_type": {"type": "string"}
  },
  "content_filter": {
    "any_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "NEWS"},
          {"type": "FILING"},
          {"type": "TRANSCRIPT", "subtype": "Special Situation, M&A and Other"}
        ]
      }
    ]
  },
  "research_plan": {
    "title": "M&A Analysis Framework",
    "steps": [
      {"description": "Research transaction details and timeline"},
      {"description": "Analyze deal terms and valuation metrics"},
      {"description": "Evaluate strategic fit and synergy potential"},
      {"description": "Review regulatory filings and antitrust considerations"},
      {"description": "Gather analyst reactions and market sentiment"},
      {"description": "Synthesize findings and outlook"}
    ]
  },
  "expected_output": "# M&A Transaction Analysis\n## Transaction Overview\n## Financial Terms & Valuation\n| Metric | Value |\n| --- | --- |\n## Synergies & Integration Risks\n## Regulatory Considerations\n## Market Reaction\n## Competitive Impact"
}

​
Creating Templates via API

import requests
from dotenv import load_dotenv
import os

load_dotenv()
my_api_key = os.getenv('BIGDATA_API_KEY')

template = {
    "name": "Quarterly Earnings Preview",
    "description": "Pre-earnings analysis for upcoming quarterly reports",
    "prompt": """Prepare an earnings preview for {{ company_id }} ahead of their upcoming quarterly report.

Include:
1. Consensus estimates (revenue, EPS)
2. Key metrics to watch
3. Recent business developments
4. Management guidance and commentary
5. Analyst sentiment and price targets
6. Potential catalysts or risks""",
    "expected_input": {
        "company_id": {"type": "rp_entity_id"}
    },
    "content_filter": {
        "any_of": [
            {
                "type": "DOCUMENT_TYPE",
                "document_types": [
                    {"type": "TRANSCRIPT", "subtype": "Earnings Call"},
                    {"type": "NEWS"}
                ]
            }
        ]
    }
}

response = requests.post(
    "https://agents.bigdata.com/v1/workflow/templates",
    headers={
        "X-API-KEY": my_api_key,
        "Content-Type": "application/json"
    },
    json=template
)

created = response.json()
print(f"Created template: {created['id']}")
print(f"Name: {created['name']}")

​
Best Practices

  1. Clear, specific prompts: Include numbered sections or bullet points for structured output
  2. Appropriate input types: Use rp_entity_id for entities to enable entity-aware search
  3. Content filters: Restrict to relevant document types for focused research
  4. Research plans: Add plans for complex, multi-step analyses
  5. Expected output: Define expected_output when you need consistent report structure across runs; keep format out of the prompt
  6. Descriptive names: Use clear template names for easy identification
  7. Documentation: Add descriptions explaining the template’s purpose

​
Next Steps

Research Plans

Learn how research plans affect execution

Example Templates

Ready-to-use financial analysis templates