Symbol returns

GET/v1/symbols/{symbol}/returnsPromised whole

Monthly and annual returns for the security and its benchmark, side by side.

Parameters

symbolpathrequired
Ticker symbol, case-insensitive.

Response contract

Every field in the response is part of the contract.

Response fields

The top level keys a live response actually returned, read off the API rather than written down here.

symbolannualReturnsmonthlyReturnsbenchmarkSymbolbenchmarkAnnualReturnsbenchmarkMonthlyReturns

How this was verified

Called against 3 different subjects on the live API. Every field it returned, at every level, was compared with the contract above. Last checked August 18, 2026.

Request

curl "https://api.massari.ai/v1/symbols/AAPL/returns" \
  -H "Authorization: Bearer $MASSARI_TOKEN"

Example response

{
  "symbol": "AAPL",
  "annualReturns": [
    {
      "year": "1993",
      "return": -50.22129047286277
    },
    {
      "year": "1994",
      "return": 35.1427234440806
    }
  ],
  "monthlyReturns": [
    {
      "year": "1993",
      "month": 2,
      "return": -10.73841136734217,
      "yearMonth": "1993-02"
    },
    {
      "year": "1993",
      "month": 3,
      "return": -2.8444676409186243,
      "yearMonth": "1993-03"
    }
  ],
  "benchmarkSymbol": "SPY",
  "benchmarkAnnualReturns": [
    {
      "year": "1993",
      "return": 8.640485638582728
    },
    {
      "year": "1994",
      "return": 0.3973206618194336
    }
  ],
  "benchmarkMonthlyReturns": [
    {
      "year": "1993",
      "month": 2,
      "return": 1.0673102041324434,
      "yearMonth": "1993-02"
    },
    {
      "year": "1993",
      "month": 3,
      "return": 2.240082710746294,
      "yearMonth": "1993-03"
    }
  ]
}

A real response from the live API, captured August 18, 2026. This one is CUT: long arrays, wide objects and long strings were trimmed to keep it readable, so treat it as a sample of the shape rather than all of it. Either way it is valid JSON.