Get Agent Trace
What it’s for
- Debugging runs — see the exact searches, scrapes, and extractions the agent performed, each tool’s input (
tool_call.started) and result (tool_call.finished), and where a run went wrong (error.occurred, and the terminalrun.finishedevent’soutcomeand structurederror). - Live progress UIs — poll the trace while a job is
processingto show what the agent is doing in real time.progress.reportedevents carry the run’s phase (planning,working,finalizing) with a human-readable message, andreasoning.summaryevents narrate the agent’s thinking. - Live browser view — pass
?liveView=truewhile a run is in flight to getactiveBrowserSessions: the run’s active browser sessions, each with aliveViewUrlyou can embed to watch (or demo) the agent browsing. - Cost tracking —
creditsUsedreports credits consumed so far, capped at the run’smaxCreditsif one was set.
How it works
Events are emitted by the run’s agents — theorchestrator and its subagents — and each event identifies its emitter in the agent field. Browser work happens inside an agent’s own browser session and is reported through browser.session.* events, not by separate browser agents. Order events by producerSequence (per emitting agent). The type field discriminates the 13 event variants; see the response schema below for the full list and each variant’s fields.
artifact.updated events don’t carry the artifact content itself — they reference it by snapshotId, which you fetch with the snapshot endpoint.
Events can continue to land for a moment after run.finished arrives, so if you’re polling a live run, keep a short tail window open before rendering the final state.
400.Are you an AI agent that needs a Firecrawl API key? See firecrawl.dev/agent-onboarding/SKILL.md for automated onboarding instructions.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The ID of the agent job
Query Parameters
If "true", include the currently active browser sessions with live view URLs.
true, false Response
Successful response
Canonical execution events for the run; order by producerSequence. artifact.updated events carry the snapshotId values used by the snapshots endpoint.
A canonical execution event from an agent run. Every event carries the envelope fields schemaVersion, eventId, runId, occurredAt, producerSequence and agent; the type field discriminates the variant. usage.recorded events are internal and never exposed, and agent.started events omit the model field.
- run.started
- run.cancel_requested
- run.finished
- agent.started
- agent.finished
- browser.session.started
- browser.session.finished
- progress.reported
- reasoning.summary
- tool_call.started
- tool_call.finished
- artifact.updated
- error.occurred
Credits consumed so far, capped at maxCredits if one was set.
Currently active browser sessions (only present when liveView=true).

