Sep 2025
When a run fails, you need to understand why. BrowserPilot keeps the full run history: every step, every action, every screenshot, every navigation, the error that ended the run.
You can replay the run step by step in the dashboard, watch what the agent saw, and understand what went wrong. This is the rich context. Use it.
On your side, the minimum you should log is the run id and the task you submitted. That is the join key back to the full replay. When a user reports a problem, you can ask 'what run id did you use?' and immediately pull up the full session.
Do not try to re-derive the failure from your own logs. You have error messages, stack traces, maybe some debug output. These tell you what your code did, not what BrowserPilot did. The run is the source of truth.
If you are processing webhook events, log the run id when you receive run.failed events. If you are polling the API, log the run id when a run completes with an error. This gives you a trail connecting your system to the run.
Resist the temptation to pull detailed run information into your logs (all the steps, all the screenshots). Your log system is not a good place for that data. Instead, log a pointer: 'run 12345 failed, check dashboard' or 'run 12345 failed, see event log'. The run itself is persistent and queryable in BrowserPilot.