List signal changes
signals.listReturn approved FormulaSignal Signals in release order, newest first, for incremental polling.
When to use: Use to keep a system in step with the Record. Pass since with the release date you last saw, or follow next_cursor, and filter by product, brand, dimension or category.
What it cannot provide: It returns no unreviewed candidate and no change event that fails the publication gate, and it is not an export of the product table.
Limits: At most 25 Signals per page, newest release first. Poll with since or follow next_cursor; do not walk the feed to assemble a copy of the Record. 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 |
|---|---|---|---|
| brand | No | Only Signals for this brand, matched on the full brand name, case-insensitive. | |
| limit | No | Signals per page, 1 to 25. Defaults to the plan's page size. | |
| since | No | Only Signals released on or after this date, YYYY-MM-DD. Pass the newest release date you have already seen to poll for what is new. | |
| until | No | Only Signals released on or before this date, YYYY-MM-DD. | |
| cursor | No | The next_cursor value from the previous page. Omit it for the first page. | |
| category | No | Only Signals whose change category matches this value, case-insensitive, as shown in a Signal's change.category field. | |
| dimension | No | Only Signals of this kind of change: FORMULA, FORMULA_DOSE, SERVING, PRICE, CLAIMS, CERTIFICATION, LIFECYCLE or OTHER. | |
| product_id | No | Only Signals for this canonical product id. |
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 |