Skip to content
Suggest a correction

Choose a developer integration

Guide5 min read

Decide how Record Health Check should run and where its results should go: on a Lightning record page, in a Flow or Apex process, in a background job, in an AI agent, or in a separate process that receives Platform Events. Every option runs the same Check Sets and Checks, configured once as Custom Metadata, and returns the same statuses.

Who or what needs the resultUsePermission set the runner needs
A person looking at a recordThe record-page cardRecord Health Check Card User
A Flow that branches on the resultFlow actionsRecord Health Check User
Apex code that needs the result before it continuesThe Apex APIRecord Health Check User
A background job for many records or on a scheduleQueueable, Batch, or Scheduled ApexRecord Health Check User
An Agentforce agent answering questions about a recordAgentforce actionsRecord Health Check User
An external AI tool through the Model Context Protocol (MCP)The MCP service and its REST APIRecord Health Check MCP Integration
A separate Flow, Apex trigger, or external system after a runPlatform EventsDepends on what starts the run

Every option also needs the running user’s normal access to the records and fields the Checks read. Record Health Check never runs with more access than that user.

Platform Events add to the other options: a card run, Flow, Apex call, or background job can also publish events for a separate process.

OptionResultCan publish Platform Events
Record-page cardRows and summary counts on the pageYes, on Run or Rerun, when the card checkboxes are selected
Flow actionsStatus, counts, Reason Code, and Result JSON outputsYes, with Event Publication ACTIONABLE or ALL
Apex APIrhc.RecordHealthCheckResponse with typed results and countsYes, with withEventPublication(...)
Queueable, Batch, ScheduledA job ID only; the packaged classes do not return resultsYes, with ACTIONABLE or ALL
Agentforce actionsStructured status, counts, and diagnostic fields for the agentNo
MCP service and REST APIVersioned JSON with status, counts, and diagnostic fieldsNo

Every option uses the same five statuses:

StatusMeaning
PASSThe record meets the requirement.
FAILThe record does not meet the requirement.
SKIPPEDThe Check did not apply, or its prerequisite did not pass.
UNABLE_TO_EVALUATEAccess, configuration, or data prevented a reliable answer.
ERRORAn unexpected problem stopped the Check.

For a whole Check Set, the most serious status wins, in this order: ERROR, UNABLE_TO_EVALUATE, FAIL, PASS, SKIPPED. Automation should decide from statuses, Reason Codes, and Qualified API Names, never from message text that an administrator can change. See Result labels and statuses.

Some problems, such as a missing permission or an unknown Check Set, stop the request before any result exists. Flow returns them as Success false with an Error Type; Apex throws an exception.

LimitValue
Records per Apex request or Flow group200
Active Checks in a Check Set25
Records in a packaged Queueable job200
Records in a packaged Batch or Scheduled job2,000
Formula evaluations per transaction95
Check evaluations the card runs at once on one page8, shared by every card on the page

Platform limitations states what happens when each limit is exceeded.

Each output reports its own contract version, which changes only when that output’s shape changes, independently of the package version:

OutputContract version in 2.0.11
Flow action Contract Version output2.0
Agentforce action Contract Version1.0
REST API contractVersion1.0
Platform Event Contract Version field1.0

Read the version from the output you process, and send an unexpected version to review.

Record Health Check reports on records. These needs are met with other features:

NeedHow
Keep a result historyRecord Health Check stores no results. Save them from Flow, Apex, or receiving automation in an object your team creates.
Block a record saveRecord Health Check never blocks a save. Use a validation rule.
Fix recordsRecord Health Check never changes records. Link to the fix with the Check’s Action URL, or build automation that acts on a FAIL.
Run when a record changesRecord Health Check runs only when something starts it. Start it from a record-triggered Flow, Apex, or a job.
Rely on eventsSalesforce can deliver an event more than once. Skip Event IDs you already saved, and monitor failures.
Give users accessRecord Health Check never grants access. Give the running user access to the records and fields the Checks read.