/v1/ask — the answer engine

/v1/ask runs an agent loop over the same corpus tools the MCP server exposes and returns a structured answer where every numeric claim carries a [n] citation that resolves to a src_id + source URL. It never guesses: if retrieval comes up empty, you get a refusal, and that costs zero credits.

Request

curl https://api.signals.ai/v1/ask \
  -H "Authorization: Bearer $SIGNALS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How has Uber take rate trended and what did management say?",
    "symbols": ["UBER"],
    "sources": ["kpis", "transcripts", "filings"],
    "mode": "fast"
  }'

Field	Notes
`question`	Required.
`symbols`	Optional scope. Omit for corpus-wide resolution.
`sources`	Optional restriction to specific datasets.
`mode`	`fast` = 1 credit (single retrieval pass) · `deep` = 5 credits (agentic).
`as_of`	Answer with data as of a date (default now).

Response

{
  "answer_md": "Uber's take rate expanded to **28.4%** in Q1 2026 [1], up from 27.1% a year earlier [2]…",
  "citations": [
    { "n": 1, "src_id": "src_kpi2_ab12…", "dataset": "kpis", "symbol": "UBER:US",
      "period": "2026Q1", "quote": "take rate reached 28.4%…", "source_url": "…" }
  ],
  "data_points": [ { "metric_key": "take_rate", "period": {"…": "…"}, "value": {"…": "…"}, "src_id": "…" } ],
  "confidence": "high",
  "not_found": null,
  "credits": { "used": 1, "remaining": 99 },
  "model_version": "ask-v1.0",
  "request_id": "req_…"
}

The quality bar

Every number in answer_md carries a [n] that resolves to a citation with a src_id. Uncited numeric claims are stripped by a post-generation validator.
If retrieval is empty, answer_md is null and not_found explains what was searched. A refusal costs 0 credits.

Credits

Ask calls draw from a monthly credit grant (Free 25 · Starter 500 · Builder 5,000 · Scale 50,000). Check your balance at developers.signals.ai.