Query Modes - AI Baseline API

Use POST https://api-beta.ai-baseline.xyz/v2/sandp_500/query to query filing evidence. Every request includes a natural-language query and can optionally set mode, effort, metadata_filters, include, and stream. The minimal request body contains only query:

{
  "query": "What supply chain risks did Apple disclose in its 10-K filings?"
}

That request defaults to mode: "basic" and effort: "medium". It returns rendered evidence, evidence_instructions, and summary by default. Answer generation is opt-in with include.answer: true.

Modes

Mode	Use when	Answer	Metadata filters
`basic`	You need the fastest retrieval path and do not need metadata filters.	Opt in with `include.answer: true`	No
`research`	You want metadata-filtered retrieval with optional metadata analysis.	Opt in with `include.answer: true`	Yes
`agentic_research`	You want the API to decompose a higher-effort or comparative question into subqueries.	Opt in with `include.answer: true`	Yes

basic rejects non-empty metadata filters. If you send metadata_filters, explicitly set mode to research or agentic_research.

Effort

effort controls how much work the API spends on supporting evidence. The default is medium.

Effort	Typical use
`low`	Fast, focused lookups.
`medium`	Default balance of effort and latency.
`high`	Higher effort for difficult or comparative questions.

Include Controls

The include object controls optional response sections:

{
  "include": {
    "answer": false,
    "evidence": true,
    "evidence_format": "rendered",
    "metadata_distribution": true,
    "analysis": true,
    "metadata_dashboard": true,
    "summary": true
  }
}

Field	Values	Default
`answer`	`true` or `false`	`false`
`evidence`	`true` or `false`	`true`
`evidence_format`	`"rendered"` or `"xml"`	`"rendered"`
`metadata_distribution`	`true` or `false`	`false`
`analysis`	`true` or `false`	`false`
`metadata_dashboard`	`true` or `false`	`false`
`summary`	`true` or `false`	`true`

answer: true enables answer generation. By default, retrieval runs without answer generation and returns rendered evidence, evidence_instructions, and summary. For the lowest-latency retrieval-only workflow, keep include.answer and include.analysis set to false and request only retrieval outputs such as evidence, metadata_distribution, metadata_dashboard, or summary. This removes the LLM overhead associated with answer and analysis generation. evidence: true returns grounding evidence directly in top-level evidence and includes top-level evidence_instructions for downstream answer generation. Use evidence_format: "rendered" for XML-like grounding with a trailing <source_key> quick reference, or evidence_format: "xml" for the same grounding without that source-key footer. metadata_distribution: true returns structured metadata distribution keyed by canonical field names such as sec_ticker and sec_form_type. Each metric entry includes a readable display_name plus values for distributions, or value for text summaries. metadata_dashboard: true can return the rendered dashboard independently. analysis: true generates analysis for research and agentic_research. basic rejects analysis: true. Set analysis: true with answer: false when you want analysis without answer generation. summary contains the selected mode, effort, submitted_metadata_filters, applied_metadata_filters, warnings, and evidence_count, which counts the retrieved evidence paths used to ground the response. For agentic_research, retrieval_plan.queries[].applied_metadata_filters shows the metadata filters applied to each retrieval branch.

​Modes

​Effort

​Include Controls

Modes

Effort

Include Controls