get_options_flow_timeline
Read-onlyIdempotent
Retrieve historical options flow for a stock, sorted newest first. Use to check how long a stock has been bullish or view its options flow timeline.
Instructions
Return the historical options flow for a single stock — most recent days first. Use when the user asks 'show me X's options flow history' or 'how long has X been bullish'. Returns { symbol, limit, count, data: [daily rows, newest first] }. Tier: Pro only.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Stock ticker | |
| limit | No | Days of history (max 365) |
Implementation Reference
- src/tools/optionsFlow.ts:98-109 (handler)The main handler function for get_options_flow_timeline. Parses input (symbol + optional limit), uppercase the ticker, and calls the API endpoint /options-flow/{symbol} with a 5-minute cache.
export async function handleGetOptionsFlowTimeline( ctx: McpContext, rawArgs: unknown ): Promise<unknown> { const args = GetOptionsFlowTimelineInputSchema.parse(rawArgs); const sym = args.symbol.toUpperCase(); const limit = args.limit ?? 60; const key = `options-flow:timeline:${sym}:${limit}`; return ctx.cache.wrap(key, 300_000, () => ctx.apiClient.get(`/options-flow/${encodeURIComponent(sym)}`, { limit }) ); } - src/tools/optionsFlow.ts:30-33 (schema)Zod schema defining input validation: 'symbol' (required, uppercase regex) and 'limit' (optional, 1-365, default 60).
export const GetOptionsFlowTimelineInputSchema = z.object({ symbol: z.string().regex(symbolRegex).describe("Stock ticker"), limit: z.number().int().min(1).max(365).default(60).optional().describe("Days of history (max 365)"), }); - src/tools/optionsFlow.ts:57-63 (registration)Tool definition with name, description, input schema (converted from Zod to JSON schema), and read-only annotations.
{ name: "get_options_flow_timeline", description: "Return the historical options flow for a single stock — most recent days first. Use when the user asks 'show me X's options flow history' or 'how long has X been bullish'. Returns { symbol, limit, count, data: [daily rows, newest first] }. Tier: Pro only.", inputSchema: z.toJSONSchema(GetOptionsFlowTimelineInputSchema) as Tool["inputSchema"], annotations: READ_ONLY_ANNOTATIONS, }, - src/tools/index.ts:78-78 (registration)Handler wire-up in the HANDLERS record, mapping the tool name string to the imported handler function.
get_options_flow_timeline: (ctx, args) => handleGetOptionsFlowTimeline(ctx, args), - src/tools/index.ts:51-55 (registration)The get_options_flow_timeline tool is included in the global tool registry via the optionsFlowTools spread into ALL_TOOLS, which is served by the ListToolsRequestSchema handler.
const ALL_TOOLS: Tool[] = [ PING_TOOL, ...screenersTools, ...patternsTools, ...optionsFlowTools,