Snapshot Tools

This document provides API documentation for the point-in-time financial snapshot tools.

get_point_in_time_snapshot(ticker: str, as_of: str, price_days: int = 10, filing_limit: int = 8, news_days_back: int = 7, include_news: bool = True, include_social: bool = False, use_cache: bool = True, refresh_cache: bool = False) -> dict

Return an AI-friendly Markdown historical financial snapshot for a ticker as of a specific date.

Snapshot v0 costs 1 credit and requires API key authentication.

Parameters

• ticker (str): Stock ticker symbol.
• as_of (str): Historical snapshot date in YYYY-MM-DD format.
• price_days (int): Number of recent price days to include.
• filing_limit (int): Maximum number of SEC filings to inspect.
• news_days_back (int): Historical news and social lookback window in days.
• include_news (bool): Whether to include experimental Google News RSS context.
• include_social (bool): Whether to include experimental Arctic Shift Reddit context.
• use_cache (bool): Whether to read/write the local SQLite snapshot cache.
• refresh_cache (bool): Whether to rebuild the snapshot and overwrite cache.

Snapshot Contents

• Market context: recent OHLCV, performance metrics, technical indicators, and market interpretation ending at as_of.
• SEC filings: filings filtered by acceptanceDateTime <= as_of.
• SEC financials: latest available CompanyFacts and recent quarterly facts available before as_of.
• Parsed filing excerpts: selected sections from available SEC filings.
• Historical news context: experimental Google News RSS context when available.
• Metadata: point-in-time rule, sources, warnings, and cache information.

Sample Response

{
  "ticker": "AAPL",
  "as_of": "2022-03-01",
  "format": "markdown",
  "data": "# AAPL Point-in-Time Financial Snapshot\n\n**As of:** 2022-03-01\n**Company:** Apple Inc.\n**CIK:** 0000320193\n\n## Market Context\nPeriod analyzed: ...",
  "metadata": {
    "point_in_time_rule": "SEC filings/facts filtered by acceptanceDateTime/filed <= as_of. Prices end at as_of. News/social are experimental historical search sources.",
    "sources": [
      "SEC EDGAR submissions",
      "SEC CompanyFacts",
      "Yahoo Finance via yfinance",
      "Google News RSS (experimental)"
    ],
    "older_sec_filing_files_checked": 0,
    "warnings": [],
    "cache": {
      "status": "miss",
      "key": "...",
      "created_at": "...",
      "expires_at": null
    }
  }
}

Returns

• dict: A response object containing ticker, as_of, format, Markdown snapshot data, and metadata.

HTTP API: GET /snapshot

The same snapshot is available through the REST API.

Endpoint

GET https://mcp.plusefin.com/api/snapshot?ticker=AAPL&as_of=2022-03-01

Authentication

Pass the API key in the Authorization header.

curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  "https://mcp.plusefin.com/api/snapshot?ticker=AAPL&as_of=2022-03-01"

Parameters

• ticker (str, required): Stock ticker symbol, for example AAPL.
• as_of (str, required): Historical snapshot date in YYYY-MM-DD format.

Cache Behavior

• Uses local SQLite snapshot cache by default.
• Historical snapshots where as_of is before today do not expire.
• Same-day snapshots expire after 1 hour.

Returns

• dict: A response object containing ticker, as_of, format, Markdown snapshot data, and metadata.