> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forwardmodel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The scores API

> One endpoint returns the published scores for the stocks you name.

One endpoint returns the published scores for the stocks you name.

```
GET https://api.forwardmodel.ai/v1/scores
Authorization: Bearer fm_live_...
```

## Parameters

| Parameter | Required | What it does |
| - | - | - |
| `symbols` | yes | Up to 50 US stock tickers, comma-separated, such as `COST,MSFT,BRK-B`. Share classes use a hyphen (`BRK-B`). Letters are upper-cased for you; repeats are dropped. |
| `date` | no | A trading day as `YYYY-MM-DD`. Leave it out for the latest published scores. Plus covers the last 21 trading days; older days come with an Enterprise licence. |
| `detail` | no | `full` or `short`. Defaults to `full` for 1 to 10 symbols (after repeats are dropped) and `short` for more. |

## The response

```json theme={null}
{
  "date": "2026-11-16",
  "of": 2926,
  "entries": [
    {
      "symbol": "COST",
      "name": "Costco Wholesale Corp",
      "date": "2026-11-16",
      "context_through": "2026-11-13T16:00-05:00",
      "scored_at": "2026-11-16T04:47-05:00",
      "set_at": "2026-11-16T07:14-05:00",
      "score": 6.83,
      "out_of": 10.0,
      "band": "Above average",
      "top_pct": 35,
      "summary": "A steady business whose members keep coming back, with thin margins that leave little room for rising costs.",
      "for": ["Members keep renewing at near-record rates", "More shoppers are coming through the doors"],
      "against": ["Thin margins leave little room for rising costs", "A slowdown in big-ticket spending would weigh on sales"],
      "watch": ["November sales, out in early December"],
      "graded_after_trading_days": 21,
      "notice": "Published score, the same for everyone. Not personal investment advice."
    }
  ],
  "not_scored": [
    {"symbol": "SPY", "reason": "Not in the day's scored stocks (funds and other non-equities aren't scored)."}
  ],
  "scores_left_words": "plenty left"
}
```

This example is illustrative; your answer carries that day's real values.

### Top level

| Field | What it is |
| - | - |
| `date` | The trading day these scores are for. |
| `of` | How many stocks were scored that day. |
| `entries` | One entry for each requested stock that was scored, in the order you asked. |
| `not_scored` | Requested symbols with no score that day (funds, ETFs, unknown tickers), each with a `reason`. They don't count toward your plan. |
| `scores_left_words` | How much of your plan's allowance is left until it renews, in words: "plenty left", "running low" or "none left until your plan renews". |

### Each entry

| Field | What it is |
| - | - |
| `symbol`, `name` | The ticker and the company. |
| `date` | The trading day of the score. |
| `score`, `out_of` | The score, 1.00 to 10.00, out of 10. See [What a score means](https://docs.forwardmodel.ai/what-a-score-means.md). |
| `band` | Strong, Above average, Middle, Below average or Weak. |
| `top_pct` | Where the stock sits among the day's scores: 35 means the top 35%. |
| `summary` | One line on the stock. |
| `for`, `against` | The main points on each side, in plain words. |
| `watch` | Things to watch, when there are any. |
| `context_through`, `scored_at`, `set_at` | The newest information used, when the stock was scored, and when the day's scores were locked. US Eastern time. |
| `graded_after_trading_days` | When this score is graded: 21 trading days later. |
| `notice` | The line to show with any score you display. |

With `detail=short`, each entry carries `symbol`, `name`, `date`, `score`, `band`, `top_pct` and `summary`.

## Counting

Each stock counts once a day (Pacific time) toward your plan, however many times you ask for it and wherever you ask: here, in Claude or ChatGPT, or in the chat. Asking for the same stock again that day is free. See [Plans and limits](https://docs.forwardmodel.ai/plans-and-limits.md).

## Every response

Every response carries an `X-Request-Id` header. Include it when you write to support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.