Flexreport Finance

Fetch the connected WEB of what recently HAPPENED to a company — the WHY behind its snapshot, and a time-ordered graph to CHAIN your next calls off. ===> `situate(symbols=[symbol])` already returns this web (newest 12 nodes) PLUS the ontology cards, cache state and an ordered plan — start there. Call this tool directly for the FULL graph or a wider `window_days`, and pair every node you chain off with get_event_ontology(event_type=node.type): the web says WHICH event, the ontology says what it entails and what to do about it. ===> A FIRST-LINE TOOL FOR SINGLE-COMPANY QUESTIONS, not a special…

Fetch a structured, POINT-IN-TIME company snapshot — no report generation needed. Returns thesis/bull/bear, financial overview (Piotroski, valuation signal), price performance + technical indicators, price targets, institutional ownership, and analyst grades for `symbol`. Synchronous and cheap — prefer this for a quick CURRENT read instead of generating a full PDF report. *** POINT-IN-TIME ONLY — THIS IS NOT A TIME SERIES. *** It captures where the company stands right now, not how it got there. Do NOT use it to answer temporal / trend / "over time" questions (e.g. "how has X evolved over th…

Open ONE numbered section of a source document — the exact earnings-call speaker turn a citation points at. The other end of a `trace_data_sources` citation, and the finest grain the platform serves: not the whole call, one turn of it. Use it to read the passage behind a number before quoting it, and to quote a speaker verbatim with the citation intact. Every argument comes off the citation you are following — a `transcript_section` citation's URL is `/query-section?name=...&symbol=...&year=...&quarter=...&n=...`, so read the four values out of it rather than deriving them. If you pulled the…

The platform's event ONTOLOGY — what an event TYPE means for everything else. Call it FIRST on any real-time, single-company, or event-driven request; it is the map the other calls are planned from. ===> `situate(...)` composes this with the event web and the cache state and hands you a plan — start there. Call this tool directly for the FULL card of an event type, a relation card, a whole family, or the unfiltered graph, when the plan did not cover what you need next. ===> REQUISITE for: any real-time / live-events request, any "what happened / why / catch me up" question, and BEFORE aiming…

Get the latest Flexreport research report(s) for one or more tickers. USE THIS BY DEFAULT. ===> THIS IS THE DEFAULT, CORRECT TOOL whenever a user asks for "the report", "research", "the latest research", "analysis", "a writeup", or "the PDF" for a ticker (e.g. "get me the latest research on SNOW"). It is the FAST path. For a symbol with a FRESH saved report plan it does not hand back a pre-built PDF: it pulls the plan itself — the JSON the platform saved when the symbol's latest material event published (brief, queries, results, format map) — and renders it straight into the user's template i…

Fetch the rows behind an event-web drilldown from its server-minted query token. Some `get_company_event_web` nodes carry `signed_query_url` in their `fetch` hint — an opaque, tamper-proof link the backend minted for exactly that node. This tool is the zero-planning rung of the chain: no query to compose, the rows come back directly. Pass either the full `signed_query_url` or just its `t` parameter; the URL form is unwrapped automatically. A token that came from a SAVED request rather than the event web belongs to `run_saved_query` instead — same endpoint, but it replays every query in the sa…

Fetch the latest LLM-selected stock picks (current rebalance holdings). Returns `picks`, the holdings selected for the most recent rebalance date — the names the backend's strategies are currently positioned in. Each pick is a record (ticker, strategy, weight, rebalance date, and related fields; values are strings). Synchronous and read-only — no auth required. Each holding also carries a CURRENT-BASKET YTD view: `ytd_return` (that stock's Jan 1 -> now price return) and the strategy-level weighted `basket_ytd_return`. For how the strategies have ACTUALLY performed since inception (the realiz…

Leaderboard of since-inception performance vs the S&P 500 for all strategy books. THE first stop for "how are the stock picks / strategies performing?". Returns `strategies`, one headline row per book — the four strategies plus the pooled optimized book — sorted by excess return over the S&P 500: {strategy_name, display_name, inception_date, since_inception_return, sp_since_inception, excess_since_inception, annualized_return, max_drawdown, sharpe, sp_sharpe, ytd_return, growth_strategy, growth_sp, days_tracked}. growth_strategy / growth_sp = what `amount` invested at inception would be wort…

Per-trade swap ledger (adds/drops) vs the S&P 500 for ONE strategy book. Answers "were the individual trades good?": across consecutive weekly rebalances, an ADD is a name newly selected and a DROP a name removed. Each ADD is measured from entry to its exit (or the latest close if still held); each DROP is the FOREGONE return from its exit to the latest close. Both are compared to the S&P 500 over the same window. Returns {strategy_name, trades: [{symbol, action, event_date, window_end, still_open, name_return, sp_return, excess}, ...] (newest first), summary: {n_adds, n_drops, avg_add_exces…

Since-inception daily track record vs the S&P 500 for ONE strategy book. Returns the realized performance of the book as actually held — chartable series plus headline stats: {strategy_name, book, inception_date, amount_invested, summary: {since_inception_return, sp_since_inception, excess_since_inception, annualized_return, max_drawdown, sharpe, sp_sharpe, ytd_return, growth_strategy, growth_sp, days_tracked, last_date}, series: [{date, strategy_cumulative, benchmark_cumulative, excess, strategy_ytd, growth_strategy, growth_sp, sharpe_expanding, holdings_count}, ...]}. The Sharpe series is …

Poll the status of an async job (a get_latest_report `rendering` task, generate_report_for_stock, generate_research_report, explore_data_catalogue, explore_data_coverage, draft_custom_dataset, screen_stocks, ...). Returns {"task_id": ..., "status": ..., "result": ...}. `status` is one of PENDING, SUCCESS, FAILURE, RETRY. `result` is populated once status is SUCCESS. A result over ~8 MB is not returned (it would take the server down): the call errors. Re-run the job scoped narrower (tickers, dates, a row limit in the wording) instead of polling it again.

Fetch a historical technical-indicator series for a symbol over a date range. Call `list_options("technical_indicators")` first for valid indicator names. An unknown symbol returns 404 and an unknown indicator returns 400 listing valid values. Returns `rows`, one record per trading day ordered by date (columns beyond date/symbol/close vary by indicator), or an empty list when there's no data in the range. Requires auth (your MCP client attaches the OAuth bearer automatically).

Read the rows of one of the user's saved datasets AS PUBLISHED — the file behind its latest_url, or a dated version. THIS is how a dashboard or an answer reads a dataset: the published file is reviewed at publish, point-in-time, and the same bytes every consumer gets. Never replay the dataset's saved query instead (run_saved_query re-runs live SQL: different rows, no review). A claude.ai artifact can't reach flexreportfinapi.com itself, so its page calls this tool. Fetches the file server-side and parses json, jsonl, csv, tsv, xml, rss and atom files into rows; rss/atom come back one row per …

Return the PDF template this user has saved, or a 404 if they have none. Call it to answer "what format am I on?", BEFORE `save_user_template` when a template may already exist (saving replaces it without history, so the user should know what they are overwriting), and whenever you are about to compose a PDF yourself from Flexreport data: lay the content out in this markup so the document matches the user's format. A 404 there is the cue to offer drafting one (`draft_user_template` -> previews -> `save_user_template`). Returns {"template_type", "template_format", "anchor", "template", "creat…

Check whether an exchange is currently open — a cheap routing helper. Returns `is_open`, a single boolean. An unknown exchange code is an error. Use it to route between the market-hours tools: when the market is CLOSED, extended-hours data lives in `get_aftermarket_data`; when OPEN, `detect_intraday_outlier_jumps` gives the live intraday read. No auth required. Unsure which exchange a ticker trades on? `get_company_snapshot` returns an `exchange` field whose value can be passed here as-is.

List the symbols with a report plan SAVED on or after `report_date` (default: TODAY) — the real-time research get_latest_report can render right now, and whether each renders in seconds or needs a rebuild. A plan is saved the moment a material event publishes for a symbol (eps_update, eps_release, 8k_release, financials_release, ir_publication, transcript_update) and nightly for company_update. This tool is the INVENTORY of those plans — it does not build or return a report. Returns `plans`, newest plan first: {"plans": [{"symbol": "NVDA", "event_type": "eps_release", "planned…

List scheduled earnings announcements within a date window, Flexreport names only. Omit both dates for "who reports today". Results are restricted to Flexreport's covered universe, so symbols outside coverage are dropped silently. The optional filters are AND-ed together. `sector`, `industry`, and `market_cap` are validated against fixed enums server-side; invalid values return a 422, so source them from the tools named in their descriptions rather than guessing. Returns `announcements` (empty list when nothing matches); values are strings and "nan" means not available yet. Requires auth (…

Enumerate the valid values for a parameter, straight from the backend. Call this BEFORE guessing a parameter value. `kind` selects which catalog; three kinds are scoped by a query parameter (`ticker`, or `q` / `cik`) and refuse the call without it: - "event_types" -> valid `event_type` for `list_realtime_events` (eps_update, company_update, biggest_mover, ...) - "financial_items" -> standardized EDGAR line items ("revenue", "operatingIncome") for a CUSTOM report's …

Pull live market events from the backend's Redis-backed cache (12h TTL). ===> Call `situate(...)` FIRST (symbols=[...] for named companies, none for the market): its `cache.present` / `cache.expired` say which types this tool can still return, its `plan` carries the exact calls to make, and its `skip` list names the ones that would return [] — an event older than the 12h cache lives in the ontology card's `persisted_in` relation, not here. Never call this for a type situate marked expired. `list_options("event_types")` remains the enumeration of valid type strings and descriptions. `event_typ…

List the data requests you have saved with `save_user_query`, newest first. The entry point to the replay flow: check HERE FIRST, before running `explore_data_catalogue` for any exploration question — a saved row that matches the question, exactly OR in shape, means the answer is seconds away via `run_saved_query` instead of a ~1-5 minute planning job. Returns {"count": N, "saved_queries": [{"id", "user_request", "queries", "query_placeholder", "metadata", "created_at", "updated_at"}, ...]}, the calling user's rows only. MATCH ON `metadata`, NOT ON THE LABEL. `metadata` describes what the r…

List the caller's scheduled tasks (cron jobs created via `schedule_task`). Returns `tasks`, only the authenticated user's jobs, each as {"name", "active", "schedule" (cron string), "args", "kwargs", "enabled", "last_run_at", "total_run_count"}. Workflow schedules are named "wf:{email}:{workflow-name}"; dataset builds (save_user_dataset) are "ds:{email}:{dataset-name}". Use `name` as the key to remove a job with `delete_scheduled_task`.

List the sub-industries within one or more sectors. Returns `industries`, the distinct industries used to narrow `list_realtime_events(industry=[...])`.

List the user's own saved datasets (from save_user_dataset) with their build status and download links to the published files. New items are reviewed before publishing, up to 40 per build (on a large first build the rest publish as queried and are reviewed on later builds; a failed review publishes the items as queried). The review can correct text from stored sources, add a one-line caveat, or hold an item out; links, GUIDs, tickers and dates are never changed. So a file can hold fewer rows than the query returns, and an item already published unreviewed can later be corrected or withdrawn. …

Get a link to the Stripe billing portal where the user can view invoices, update their card, or cancel their subscription. Use when the user asks to manage, change, or cancel their billing/subscription.

Request onboarding of a NOT-yet-covered ticker (mutating, authenticated). Kicks off a 30-60 min backend workflow and emails the authenticated user when the first report is ready. Rate-limited to 5/hour per user. Use only when a symbol is missing from `list_options("tickers")` / returns no data elsewhere. Returns {"task_id": ..., "status": "PENDING"}.

Build a risk-optimized portfolio from a non-empty list of tickers. Scores `symbols` with the multi-signal scorer, LLM-curates, and risk-optimizes. Rate-limited to 10/hour per user server-side. Asynchronous: returns {"task_id": ..., "status": "PENDING", "supported": [...], "not_supported": [...]}. Poll `task_id` with `get_task_status` until SUCCESS.

Build a risk-optimized portfolio from a list of tickers — fast, synchronous, no LLM. THE DEFAULT optimizer route. Returns the result directly and almost instantly (no task id, no polling). Reach for `optimize_portfolio` instead only when you explicitly want the slower LLM-curated variant layered on top of the optimizers. Symbols are validated against the covered universe; unsupported tickers come back in `missing`, and in-universe tickers with too little price history come back in `dropped`. No auth required (public endpoint). Synchronous. Returns: {"status": "OK", # or "SKIPPED"/"EMPTY…

Predict how big a stock's move will be when it next reports earnings. For each symbol, returns its next earnings date (today or later) and `expected_move`: the expected absolute move of the reaction session as a log return (0.05 is about 5%; size only, no direction). For context, `hist_move_mean` / `hist_move_n` give the stock's own average reaction over its past reports and how many reports that covers. Symbols with no scheduled report come back in `no_upcoming_earnings_symbols`; uncovered tickers in `not_supported_symbols`.

Save a realtime-event filter server-side and get a `subscription_id` whose stream resumes where the last read stopped (`POST /register-subscription`). For a live-streaming ask, the default is a dashboard (in Claude, an Artifact) that loops stream_events itself — see stream_events. Register a subscription when the user wants a saved filter that resumes across sessions. Returns {subscription_id, filter, cursor, created_at}. `filter` echoes the normalised filter (topics lower-cased, symbols upper-cased, duplicates dropped); `cursor` is the position the subscription starts from — only events pub…

Re-run a saved request's queries against live data — exactly, or re-aimed at other entities with typed `values`. No planning, no polling. The payoff of `save_user_query`: pass a saved row's `queries` array from `list_saved_queries` and each stored query runs as-is, returning fresh rows synchronously. Use this INSTEAD of `explore_data_catalogue` whenever a saved row already covers the question — same SQL, current data, seconds instead of minutes, and it does not draw on the 20/hour exploration budget. A full signed URL is accepted in `query_tokens` and unwrapped. For a token that came from a …

Save a drafted candidate as the user's scheduled dataset (step 2 of 2, after draft_custom_dataset): its query, the schema it produces, the file format, the date mode and a cron schedule. Each build publishes a new file only when the rows changed; list_user_datasets returns the files. New items are reviewed before publishing, up to 40 per build. On a large first build the rest publish as queried and are reviewed on later builds; a review that fails publishes the items as queried. The review can correct text from stored sources (a cut-off sentence, a fiscal period missing from a title), add a o…

Save the queries an exploration already planned, so the request can be replayed instantly — exactly, or re-asked for other entities. THE POINT: `explore_data_catalogue` is a full validate -> plan -> run pipeline that re-authors the SQL from scratch on every call (~1-5 min, 20/hour). For a question the user will ask AGAIN — a recurring check, a dashboard they watch, "my usual semis screen" — save the tokens that exploration just produced. `run_saved_query` then re-runs exactly those queries against live data in seconds, with no planning step and no async job to poll. The backend ALSO authors a…

Save the user's PDF format — one template per account, applied automatically to every PDF the backend renders for them from now on. STEP 2 OF 2 after `draft_user_template`. Two ways to call it: SIGNED-OFF (the normal path): pass `draft_id` and the `variant_id` the user chose from the previews. The EXACT treatment they looked at is stored — no second adaptation pass that could produce something they never saw. `template`, `template_type` and `anchor` are taken from the draft and may be omitted. A 404 means the draft expired (24h) or the variant does not exist: draft again. DIRECT (no preview…

Save a multi-step WORKFLOW (upsert by `name`) and attach a recurring cron schedule for its delivery. Use this when the user wants a sequence of platform calls delivered ON A SCHEDULE / repeatedly (e.g. "every weekday morning pull 8-K releases, screen for cheap large-caps, and email me the overlaps as a table"). For a ONE-OFF request, call the corresponding tools directly instead. A request worded as a "datafeed" / "feed" / recurring file is draft_custom_dataset, not this — even with summary columns, since stored summaries are ordinary dataset columns. `steps` (shape in the parameter descript…

Screen stocks by financial growth, sector, sub-industry, market cap, analyst ratings, institutional ownership, country, and price performance. Discover valid filter values with the list tools named in each parameter's description before guessing. Rate-limited to 10/hour per user server-side. Asynchronous: returns a task id. Poll it with `get_task_status` until SUCCESS.

THE FIRST CALL. What is going on right now — for the market, or for the named symbols — and a ready-made PLAN of the tool calls that answer the user's question. Call it before any other flexreport tool on anything about a company, an event, or "now". ===> Call this FIRST for: "catch me up on X", "what happened / why", "anything before earnings?", "any earnings / 8-Ks / 13F moves / movers today?", "how is X trading", and BEFORE aiming explore_data_catalogue, list_realtime_events or a report tool at a company. Pass the user's question verbatim in `question`: it is matched by keyword (never an L…

Read the next events on a saved subscription — a bounded read of `GET /event-subscription/{subscription_id}` that resumes from the position saved when the previous read closed, so repeated calls see every matching event exactly once with no gap and no replay. For a live-streaming ask, the default is a dashboard (in Claude, an Artifact) that loops stream_events with its cursor — see stream_events; a page should prefer that ad-hoc stream, since a subscription read can stall. Returns {"events": [...], "cursor": "<last id seen>", "closed": null | reason, "elapsed_seconds": n} — same shape and ev…

Listen for realtime events as they publish — a bounded read of the backend's ad-hoc SSE stream (`GET /events`), filter passed inline, nothing saved server-side. DEFAULT DELIVERY — BUILD A DASHBOARD: when the user asks to stream / watch / keep listening for live events, build a live dashboard (in Claude, an Artifact) whose page calls this tool in its own loop, carrying `cursor` from read to read, and renders each event as it lands. One prompt then keeps the stream open with no agent turn per read. If the page cannot reach this server, run the loop yourself and write each event into the dashboa…

Resolve numbers you are holding back to the documents they were read from — the filing, the section, or the verified quote. The CITATION rung of the chain. `explore_data_catalogue`, `run_saved_query` and `get_signed_sql_drilldown` hand back rows; this says where each number CAME FROM. Reach for it whenever the user asks "where does that come from", "which filing", "can you cite that", "how do you know" — and unprompted before you publish a figure they are going to act on. TWO WAYS IN, and the FIRST is preferred: 1. `relation` + `keys` — `relation` is a name off the result's `sources.r…

Change your saved PDF template — any field, or none to recompile it as stored. Complements `draft_user_template` (preview), `save_user_template` (create) and `delete_user_template` (remove). Every argument is optional; a field you omit keeps its stored value, and the result is compiled into a blueprint again: - a VISUAL change: draft the new page with `draft_user_template`, show the previews, then pass the chosen `draft_id` + `variant_id` here (both or neither); - a change without previews: pass `template`, `template_type` and/or `anchor` directly (HTML only — markdown is reje…

Get a secure link for the user to upgrade or change their Flexreport Finance plan (e.g. to raise their request limit). Returns a checkout link — the user completes payment in their browser. Call this whenever the user asks to upgrade, subscribe, pay for, or change their plan, or when they've hit a usage/quota limit.