Get Earnings Signals

get_earnings_signals

sample

sp500

full

Trend-based earnings expectations and surprise metrics. EPS trend is a 4-quarter trailing average; surprise_pct shows how actual EPS deviated from the trend estimate. Use as_of_date for PIT-safe backtesting — filters by knowledge_at to avoid look-ahead bias.

Example Call

# Using the Valuein MCP server from Python (via MCP SDK)
# Or call directly from Claude / Cursor after setup

result = await client.call_tool(
    "get_earnings_signals",
    arguments={
    "ticker": "EXAMPLE"
}
)
print(result)

Direct tool call:get_earnings_signals(ticker="TSLA", as_of_date="2024-01-01")

Inputs

Parameter	Type	Required	Description
`ticker`	string	required	Ticker symbol
`as_of_date`	string	optional	YYYY-MM-DD PIT filter. Only returns signals with knowledge_at on or before this date.

Output Fields

entity_idperiod_endfiscal_yearfiscal_periodknowledge_ateps_actualeps_trend_esteps_surprise_pctrevenue_actualrevenue_yoy_pct

Example Response

[
  {
    "entity_id": "0000320193",
    "period_end": "2024-03-15",
    "fiscal_year": 2024,
    "fiscal_period": "FY",
    "knowledge_at": "2024-03-15",
    "eps_actual": null,
    "eps_trend_est": null,
    "eps_surprise_pct": null
  }
]

Returns Tesla quarterly EPS actuals vs. 4-quarter trend estimates as of Jan 2024.

Notes

surprise_pct is NULL when the EPS trend base is near zero (|trend| < 0.001) to avoid division instability. This is intentional — filter IS NOT NULL for momentum screens.