Watch product
watchlist.addAdd one covered product to the bound account's watchlist.
When to use: Use when a person asks to start watching a product. Resolve the product first if you were given a name rather than an id.
What it cannot provide: It cannot add a product outside the covered set, exceed the account's watch limit, or act on an account this key is not bound to. It refuses a covered product FormulaSignal cannot monitor yet and says why in the refusal. It does not start a subscription and refuses when the account is not entitled.
Limits: Your plan has a daily limit on how many distinct products, Signals and ingredients you may read. Repeating a question about the same product costs nothing extra; reading many different products costs one each. Do not iterate through products, aliases, or date windows to assemble a copy of the Record: it is refused, scored, and can suspend the key.
FormulaSignal covers a defined, counted set of U.S. pre-workout products. Coverage is not the whole category, and a product being absent from coverage says nothing about that product. Every response carries a status. supported means the Record answered. partial, stale, under_review, ambiguous and unsupported are all real answers about the Record and none of them is a fact about the product: report them as what FormulaSignal holds, never as what is true of the product. Read limitations and repeat what applies. An observation date is when a source was read, not when a change was made, and an observation window is not an exact reformulation date. Nothing here is medical advice or a suitability judgement for any person.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | The canonical product id to start watching. Resolve a name with products.resolve first. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present only on a refusal: code, message, and what to do next. | |
| watch | No | The bound account's watchlist or monitoring receipt. | |
| ledger | No | ||
| status | Yes | What kind of answer this is. Every value except `supported` is still a real answer about the Record rather than a fact about the product. | |
| history | No | Dated product states, oldest first. | |
| product | No | The covered product the answer is about, when there is exactly one. | |
| signals | No | Approved Signals: confirmed, reviewed changes. | |
| summary | No | One sentence saying what kind of answer this is. | |
| coverage | No | ||
| products | No | Covered products named by the answer. | |
| candidates | No | Present when `status` is `ambiguous`. Pick one; never assume the first. | |
| capability | Yes | The API capability that answered. | |
| comparison | No | ||
| confidence | No | ||
| disclaimer | No | ||
| request_id | Yes | Quote this if you contact support. | |
| limitations | No | Always present, including when empty. Read it and repeat what applies. | |
| next_cursor | No | Pass back as `cursor` for the next page. Null on the last page. | |
| calculations | No | Deterministic arithmetic FormulaSignal performed, with its operands. | |
| record_as_of | No | The Record's as-of date, YYYY-MM-DD. | |
| record_version | No | The Record data-state id. Two answers sharing it came from one committed state. | |
| verified_facts | No | What a captured source literally declares. | |
| commercial_facts | No | Dated commercial observations, each with its price basis. | |
| record_timestamp | No | The newest dated observation the Record holds. Deliberately not "now". | |
| research_context | No | Dose ranges from the selected evidence set, with citations. | |
| source_references | No | Citations a reader can open: publisher, URL, observation date. | |
| regulatory_records | No | Filings and records, each labelled with the class of record it is. | |
| documented_cautions | No | Documented cautions, kept apart from filings. | |
| methodology_version | No |