Query Modes

Choose the right query mode, effort level, and response sections.

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	Metadata filters
basic	You need the fastest retrieval path and do not need metadata filters.	No
research	You want metadata-filtered retrieval with optional metadata analysis.	Yes
agentic_research	You want the API to decompose a higher-effort or comparative question into subqueries.	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": {
    "evidence": true,
    "evidence_format": "rendered",
    "evidence_instructions": true,
    "agent_context": false,
    "metadata_distribution": true,
    "metadata_dashboard": true,
    "summary": true,
    "answer": false,
    "analysis": true
  }
}

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

evidence: true returns grounding evidence directly in top-level evidence. Use evidence_format: "rendered" for XML-like grounding with a trailing <source_key> quick reference. This is the recommended default when you want grounded context to pass to your own LLM. Use evidence_format: "xml" for the same grounding without that source-key footer.

evidence_instructions: true returns top-level evidence_instructions, a separate string containing domain-owned guidance for how a downstream LLM should use the returned evidence to generate a grounded answer. These instructions are returned by default when evidence is included and are not part of the evidence content itself. Set evidence_instructions: false to omit them.

agent_context: true returns top-level agent_context, a derived convenience payload intended for direct handoff to another LLM or agent. It is not the canonical evidence contract. evidence remains the canonical grounding evidence field, and evidence_instructions remains the canonical downstream answer-generation guidance field.

agent_context.content_type is currently always "text/markdown". agent_context.text combines the domain-owned evidence-use instructions with the selected evidence format. agent_context.source_fields lists the canonical response fields used to construct the payload.

agent_context honors include.evidence_format: with "rendered", the context includes rendered evidence; with "xml", it includes XML evidence with the same public XML formatting behavior as top-level evidence.

Clients building custom prompts or UIs should use evidence and evidence_instructions directly. Use agent_context when you want one ready-to-feed context block and do not need separate raw fields.

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.

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.

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, agent_context, metadata_distribution, metadata_dashboard, or summary. This removes the LLM overhead associated with answer and analysis generation.

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.

For agentic_research, retrieval_plan.queries[].applied_metadata_filters shows the metadata filters applied to each retrieval branch.

Retrieval Controls

The public /query API currently supports one retrieval control:

{
  "retrieval": {
    "max_evidence": 25
  }
}

retrieval.max_evidence must be a positive integer. It controls the maximum number of evidence chains returned to the API consumer.

If retrieval.max_evidence is omitted and include.answer is false, returned evidence is not capped by the answer-generation retrieval profile top-N limit.

If include.answer is true, the selected retrieval profile cap is still enforced for answer generation. If the caller also sets retrieval.max_evidence, the lower value wins.

Other retrieval control fields are not supported on the public /query API and are rejected by request validation.

Request Examples

Structured/custom integrations can use the canonical fields directly and only override the defaults they need to change:

{
  "query": "What supply chain risks did Apple disclose in its 10-K Item 1A filings?",
  "mode": "research",
  "effort": "medium",
  "metadata_filters": {
    "sec_ticker": "AAPL",
    "sec_form_type": "10-K"
  },
  "include": {
    "summary": false
  },
  "retrieval": {
    "max_evidence": 25
  }
}

Direct LLM or agent handoff can request agent_context without duplicated raw fields:

{
  "query": "What supply chain risks did Apple disclose in its 10-K Item 1A filings?",
  "mode": "research",
  "effort": "medium",
  "metadata_filters": {
    "sec_ticker": "AAPL",
    "sec_form_type": "10-K"
  },
  "include": {
    "evidence": false,
    "evidence_instructions": false,
    "agent_context": true
  }
}

That request returns agent_context and omits top-level evidence and evidence_instructions.