Agent Endpoints
Get Agent Trace
GET
Get the execution trace of an agent job
Every agent run records a canonical execution trace: an ordered stream of events describing everything the run did — which tools it called and what they returned, reasoning summaries, progress updates, browser sessions, and changes to its output artifacts. This is the same event stream that powers the live Activity view in the Agent playground.
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.
Traces are recorded on Spark 2 runs — which is every new run. Jobs started on Spark 1 models before their retirement have no trace and return
400.Are you an AI agent that needs a Firecrawl API key? See firecrawl.dev/agent-onboarding/SKILL.md for automated onboarding instructions.
Authorizations
Query Parameters
Response
Successful response
events
(run.started · object | run.cancel_requested · object | run.finished · object | agent.started · object | agent.finished · object | browser.session.started · object | browser.session.finished · object | progress.reported · object | reasoning.summary · object | tool_call.started · object | tool_call.finished · object | artifact.updated · object | error.occurred · object)[]
Canonical execution events for the run; group by agent.id, then order each group by producerSequence, which is monotonic per emitting agent. 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

