For coding agents

​

The contract

​

How the data behaves

• One set of scores per trading day. They’re published before the market opens, usually by 9:00 a.m. Eastern. Until the new day is out (early in the morning, on a market holiday, or on the rare late day), a call returns the latest published day. If the new day isn’t out by 9:30 a.m. Eastern, use the latest day and check again later.
• Check date. The top-level date tells you which trading day you got. Compare it with today’s date in US Eastern time.
• A day’s scores never change. Cache each answer by (symbol, date) and don’t ask again that day. A repeat call returns the same values.
• Batch. Ask for up to 50 symbols in one call instead of one call per symbol. When you split a long list into several calls, pass the first answer’s date to the rest, so every batch is the same day.
• Some symbols aren’t scored. Funds, ETFs, unknown tickers and other non-equities come back under not_scored with a reason, not as an error, and don’t count. A symbol that can’t be a ticker (anything but letters, digits, . and -, up to 10 characters, starting with a letter) fails the whole call with invalid_input.
• Compare within a day. A score is a position among that day’s scored stocks. Don’t compare one day’s score with another day’s.
• Show the notice. When you show a score to a person, show this line with it: “Published score, the same for everyone. Not personal investment advice.” Full entries carry it as notice.

​

How the plan counts

• A stock counts once per day, Pacific time (midnight to midnight in Los Angeles), whichever day’s score you get. Asking for it again that day, including after the new scores come out, is free. So checking early in the morning wastes nothing.
• The allowance resets when the plan renews each month. scores_left_words in each answer says, in words, how much is left until then: “plenty left”, “running low” or “none left until your plan renews”. Slow down when it says running low.
• There’s also a daily limit. It resets at midnight Pacific time.
• At the limit, the whole call is refused with limit_reached and nothing in it counts. resets_at says when: the next midnight Pacific for the daily limit, or the plan’s renewal for the monthly one (null if not known). Stocks you’ve already seen that day still come back if you ask for only those.

​

Response schema

​

Errors

​

A complete client

import os, time, requests

BASE = "https://api.forwardmodel.ai"
KEY = os.environ["FORWARD_MODEL_API_KEY"]          # never print or log this
RETRY = {"rate_limited", "model_unavailable", "server_error"}


def get_scores(symbols, date=None, detail=None, tries=3):
    """Today's scores (or a given trading day's) for up to 50 tickers."""
    params = {"symbols": ",".join(symbols)}
    if date:
        params["date"] = date
    if detail:
        params["detail"] = detail
    for attempt in range(tries):
        r = requests.get(f"{BASE}/v1/scores", params=params,
                         headers={"Authorization": f"Bearer {KEY}"}, timeout=30)
        if r.ok:
            return r.json()
        try:
            err = r.json().get("error", {})
        except ValueError:                             # not JSON: a gateway error, treat as temporary
            err = {"type": "server_error", "message": r.text[:200]}
        if err.get("type") in RETRY and attempt < tries - 1:
            time.sleep(int(r.headers.get("Retry-After", err.get("retry_after_seconds", 5))))
            continue
        raise RuntimeError(f"{r.status_code} {err.get('type')}: {err.get('message')} ({err.get('request_id')})")


def get_many(symbols):
    """Any number of tickers, 50 at a time, all from the same trading day."""
    out = {"date": None, "entries": [], "not_scored": []}
    for i in range(0, len(symbols), 50):
        part = get_scores(symbols[i:i + 50], date=out["date"])   # the first answer's day for every batch
        out["date"] = part["date"]
        out["entries"] += part["entries"]
        out["not_scored"] += part["not_scored"]
    return out


if __name__ == "__main__":
    day = get_scores(["COST", "MSFT"])
    print("Scores for", day["date"])
    for e in day["entries"]:
        print(f'{e["symbol"]:6} {e["score"]:5.2f}  {e["band"]}')

​

In an AI assistant instead