ingredients.regulatoryread-only | Return regulatory records and documented cautions for named ingredients, each carrying the class of record it actually is.
When to use: Use when you need to know what filings, advisories, label warnings, interactions, or enforcement actions FormulaSignal holds for an ingredient.
What it cannot provide: A regulatory filing is never returned as an approval, a warning, or a finding of harm. Nothing here is medical clearance.
Limits: Pass ingredient_ids (at most 5) or one product_id, not both. 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. |
ingredients.researchread-only | Return the dose range used in the selected evidence set for named ingredients, with the citation and its limitations.
When to use: Use to place a declared amount against published work. Pass ingredient ids, or a product_id to read the ingredients that product declares.
What it cannot provide: A dose comparison is not evidence of effectiveness, safety, or suitability for any person, and the response says so on every record.
Limits: Pass ingredient_ids (at most 5) or one product_id, not both. 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. |
ledger.getread-only | Return one Category Ledger edition: the executive summary, confirmed changes released in the period, category benchmarks with their cohorts, serving economics, the product comparison, and the limitations.
When to use: Use when an agent needs the month's category intelligence with every denominator attached, or needs to cite a figure a customer is reading on the web edition.
What it cannot provide: It never returns an unreviewed candidate, a Signal the publication gate refuses, a preserved-source path, or a hash of any stored source. The edition_hash it does return is a hash of the published document itself, so a machine citation and the page a person was sent can be checked against each other.
Limits: One edition per call. Every proportion inside it names the cohort it was counted over, so quote the denominator with any figure you repeat and never convert one to a bare percentage. 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. |
ledger.listread-only | List the published Category Ledger editions: period, status, data-as-of date and the count released in each.
When to use: Call this first to find which edition covers a period, then fetch that edition by id.
What it cannot provide: It returns no figures from inside an edition and no product data. A closed edition's identity never changes, so this list is safe to cache.
Limits: Identities only. A frozen edition never changes, so its listing and its content are both safe to cache; an in-progress one moves until its period closes. 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. |
products.compareread-only | Compare two or three covered products on consistent FormulaSignal criteria.
When to use: Use when a user asks how covered products differ on formula, serving economics, stimulant load, or record depth.
What it cannot provide: It returns no overall winner and no suitability judgement. A product whose depth is REGISTERED is refused rather than compared, because a guessed label beside a measured one implies a precision the Record does not have.
Limits: At most 3 products per call, and every product must be at NORMALIZED depth. 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. |
products.getread-only | Return the controlled current Record for one covered product: identity, serving configuration, declared ingredients, captured price context, and freshness.
When to use: Use when you need what a product declares right now, with the dates and limitations attached.
What it cannot provide: It returns no preserved source bytes, no internal capture identifiers, no review notes, and no verdict about whether the product is good or suitable.
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. |
products.historyread-only | Return the controlled historical timeline for one covered product, with each state classified by what it can actually support.
When to use: Use to find out whether a product has changed, how deep the recoverable history is, and which states are comparable to each other.
What it cannot provide: It never presents an observation window as an exact reformulation date, and it never reports an unreviewed candidate as a confirmed change.
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. |
products.resolveread-only | Resolve a brand, product name, or alias to one canonical covered product.
When to use: Call this first whenever you hold a user-supplied product name and need the canonical product_id every other capability takes.
What it cannot provide: It never guesses. An ambiguous or generic name returns the candidate list and no match, and an uncovered product returns no match at all.
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. |
products.serving_economicsread-only | Return the captured commercial facts and the deterministic price arithmetic for one covered product.
When to use: Use for package price, price basis, serving count, price per serving, and the date each was observed.
What it cannot provide: It never calls an observed price a list price unless the Record recorded it as one, and it never reports a promotional-versus-list difference as a price change.
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. |
record.searchread-only | Answer one specific, bounded question from FormulaSignal's covered pre-workout Record.
When to use: Use for a single natural-language question about a covered product: what it declares now, whether it changed, what it costs per serving, or which covered products meet one stated numeric condition.
What it cannot provide: It cannot list the database, export products, answer medical or suitability questions, or answer about a product FormulaSignal does not cover.
Limits: One question, at most 300 characters. 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. |
record.versionread-only | Return the public Record version, the methodology version, the supported category, coverage counts, and source freshness.
When to use: Call this to state which version of FormulaSignal intelligence an answer came from, or to detect that coverage has moved.
What it cannot provide: It exposes no implementation detail, no internal scoring, and no proprietary methodology text.
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. |
signals.explainread-only | Explain one approved FormulaSignal Signal: a confirmed, reviewed change between two comparable product states.
When to use: Use when a product record or history response named a signal_id and you need the before state, the after state, the observation window, and the evidence.
What it cannot provide: It has no access to unreviewed candidates, review deliberation, or the internal review queue. A signal_id that is not approved returns not found.
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. |
signals.listread-only | Return 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. |
signals.snapshotread-only | Return a bounded summary of approved Signals and coverage state across the covered pre-workout set for a date window.
When to use: Use for 'what changed in the category recently'. Pass from and to dates; the window is capped and the page size is capped.
What it cannot provide: It is not an export. It returns approved Signals inside one bounded window, never the product table and never the underlying Record.
Limits: Bounded window of at most 400 days and at most 25 items per page. Follow next_cursor for more. 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. |
watchlist.add | Add 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. |
watchlist.listread-only | Return the watchlist of the one Founding Pro account this key is bound to, with each product's monitoring state.
When to use: Use to answer what a person is watching, when each product was last read, when the next check is due, and whether anything is currently unreadable.
What it cannot provide: It reaches exactly one account, the one bound to this key, and no other. It returns no candidate detail, no source URL and no internal identifier, and it is not a way to read the covered set.
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. |
watchlist.receiptread-only | Return the monitoring receipt for one period: valid checks, attempts that returned nothing, recoveries, and confirmed Signals.
When to use: Use to answer whether anything a person watches changed in a period, and what monitoring did in the period whether or not anything did.
What it cannot provide: A count of valid checks is not a claim that a product held still. It reports no candidate, no source URL and no internal identifier, and a period the monitoring ledger does not reach is reported as partly covered rather than as zero.
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. |
watchlist.removedestructive | Remove one product from the bound account's watchlist.
When to use: Use when a person asks to stop watching a product. Future alerts stop; everything already delivered stays.
What it cannot provide: It cannot delete an account, cancel a subscription, or remove history. Removing a watch never removes what was already sent.
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. |
protogrid