Query Modes

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 retrieval. 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, evidence_budget, and summary by default.

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.	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
  }
}

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`

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 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 evidence-use instructions with the selected evidence format. For agentic_research, it also includes the task-aware coverage assessment. 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. For agentic_research, retrieval_plan.queries[].applied_metadata_filters shows the metadata filters applied to each retrieval branch.

Agentic Coverage

agentic_research currently decomposes a question into up to four independently required retrieval inputs. For financial comparisons and calculations, these can include every issuer, current and comparison periods, each requested metric, and source inputs such as a numerator and denominator. The top-level coverage object reports whether the delivered evidence covers those planned inputs:

Coverage status	Meaning
`complete`	Every planned requirement has at least one returned evidence chain, and the plan did not omit any requirements.
`partial`	Some requirements are covered while others are missing, omitted by the evidence token budget, or could not fit within the requirement-planning limit.
`none`	No planned requirement has returned evidence.
`not_assessed`	Requirement decomposition failed and retrieval fell back to the original query.

Each coverage.requirements[] item includes the requirement id, label, retrieval query, retrieved_evidence_count, returned_evidence_count, and one of these statuses:

covered: at least one associated evidence chain was returned.
missing: no associated evidence chain survived retrieval and delivery.
omitted_by_budget: evidence was available for this requirement, but none of its complete chains fit within retrieval.max_evidence_tokens.

coverage.limitations can contain planning_fallback, requirement_limit, missing_evidence, or token_budget. coverage.omitted_requirements lists required inputs that did not fit within the decomposition limit. Coverage is a retrieval-completeness signal. It means evidence was returned for every planned input; it does not independently certify that the evidence is factually correct or sufficient for a final calculation.

Retrieval Controls

The public /query API supports evidence-count and estimated-token controls:

{
  "retrieval": {
    "max_evidence": 25,
    "max_evidence_tokens": 12000
  }
}

retrieval.max_evidence must be a positive integer. It controls the maximum number of evidence chains returned to the API consumer. retrieval.max_evidence_tokens must also be a positive integer. It is a strict cap on the deterministic estimated size of the returned evidence. Selection keeps complete evidence chains, prioritizes chains that cover the most uncovered agentic requirements, and then fills the remaining budget in rerank order. The evidence and its regenerated source registry are re-estimated after each candidate, so the final estimate does not exceed the requested cap. The estimator is chars_div_4_v1, calculated as ceil(projected evidence characters / 4). It is deterministic and useful for payload planning, but it is not a provider-exact tokenizer. Evidence instructions, dashboards, and agent-context wrappers are excluded. Both controls are uncapped by default. If max_evidence is omitted, no caller-supplied chain-count cap is added after the normal retrieval, relevance filtering, and deduplication stages. If max_evidence_tokens is omitted or null, no token cap is applied. Whenever evidence or agent_context is requested, the response includes evidence_budget:

{
  "evidence_budget": {
    "requested_max_tokens": 12000,
    "estimator": "chars_div_4_v1",
    "estimated_tokens": 8460,
    "available_evidence_count": 18,
    "returned_evidence_count": 12,
    "truncated": true
  }
}

With no token cap, requested_max_tokens is null; the API returns all evidence that survived the earlier stages and provides estimate metadata only. If no complete chain fits within the requested cap, evidence is omitted rather than cut into a malformed chain. This is not reported as "No data found" because retrieval did find evidence. 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,
    "max_evidence_tokens": 12000
  }
}

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.

Get Started

Guides

API Reference

Modes

Effort

Include Controls

Agentic Coverage

Retrieval Controls

Request Examples

​Modes

​Effort

​Include Controls

​Agentic Coverage

​Retrieval Controls

​Request Examples

Modes

Effort

Include Controls

Agentic Coverage

Retrieval Controls

Request Examples