ClearRun best practices

Where to put ClearRun, how to set thresholds, and how to talk about scores. Current npm packages are 1.2.0.

Last updated November 9, 2026

Start here

Where should ClearRun go in an AI pipeline?
Put ClearRun right after the model answers and before anyone acts on it. Score the final answer with its prompt, then decide in code what a low score means.
How to choose a ClearRun score threshold
Score answers you already know are well argued and answers you know are not, then set the line between them. Step-by-step help from the ClearRun help center.
What to do when an answer gets a low ClearRun score
Treat a low score as a flag. The answer's stated confidence is ahead of the support in its reasoning. From the ClearRun help center.
How to keep ClearRun API keys out of your repo
Keep the key in an environment variable or in the file clearrun login saves. Never put it in a file you commit. Step-by-step help from the ClearRun help center.

All Best practices articles

Where should ClearRun go in an AI pipeline?
Put ClearRun right after the model answers and before anyone acts on it. Score the final answer with its prompt, then decide in code what a low score means.
How to use ClearRun in CI without blocking every pull request
Score a small fixed set of answers, run only when prompts change, and start in report-only mode. Turn on blocking in CI once you trust your ClearRun threshold.
How to choose a ClearRun score threshold
Score answers you already know are well argued and answers you know are not, then set the line between them. Step-by-step help from the ClearRun help center.
What to do when an answer gets a low ClearRun score
Treat a low score as a flag. The answer's stated confidence is ahead of the support in its reasoning. From the ClearRun help center.
How to keep ClearRun API keys out of your repo
Keep the key in an environment variable or in the file clearrun login saves. Never put it in a file you commit. Step-by-step help from the ClearRun help center.
Mock mode or hosted scores: which should I use?
Use mock mode to build and test your code without an account. Use hosted scores when you need real scores. Step-by-step help from the ClearRun help center.
How to keep verdict ids so you can look them up later
Save verdict.verdictId next to the answer it scored, in your own database or logs. With the id, anyone can look the score up later with no key. Steps inside.
How to check ClearRun receipts in your own systems
Store the receipt from each response, keep a copy of ClearRun's public keys, and check the Ed25519 signature and verdictHash when you need proof. Steps inside.
How to score many answers at once
ClearRun has no batch endpoint, so each answer is one call. Score a folder with the CLI or loop in code, stay under your per-minute limit, and wait out any 429.
How to retry when ClearRun returns 429
When ClearRun returns 429, wait the seconds in the Retry-After header, then retry. In SDK 0.3.1 the error carries that number as err.retryAfter. Code inside.
Which ClearRun errors are safe to retry?
Retry ClearRun 429, 500 UNSIGNED_VERDICT, 503 PERSIST_FAILED and network errors. Fix 400, 401, 402 and 403 first, since a retry fails the same way. More inside.
Why send the prompt with the answer (evaluate vs score)
Use /api/evaluate with the prompt when you have it. The prompt tells ClearRun what the answer was supposed to address. Read more in the ClearRun help center.
How to keep ClearRun credit use predictable
Score only the answers that matter, keep CI sample sets small and fixed, use mock mode in tests, and check Usage history each week. ClearRun help center.
How to pair ClearRun with your own source checks
Use ClearRun to find answers that sound more sure than their reasoning supports, and use your own source checks to test whether claims are true. ClearRun help.
How to share verdict ids safely
Anyone with a ClearRun verdict id sees its score, summary, issues and receipt, but not your prompt or answer. What to check before you share one. More inside.
How to pin ClearRun package versions in CI
Use an exact version, such as npx -y @clearrun/cli@1.2.0 or "@clearrun/sdk": "1.2.0" in package.json. Step-by-step help from the ClearRun help center.
How to tag ClearRun calls with modelId and sessionId
Add modelId and sessionId to ClearRun evaluate calls. modelId records which model wrote the answer, and sessionId groups calls, such as a test run. More inside.
How to show ClearRun scores to your users without overclaiming
Label it as an honesty score, say in one line what it means, and never call an answer "verified" or "true" because of it. Read more in the ClearRun help center.
Should I score non-English text?
Not for decisions. ClearRun is built for English text today. You can send other languages, but don't rely on those scores. ClearRun does not translate.

Start here

All Best practices articles

Other topics