Skip to main content
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 terminal run.finished event’s outcome and structured error).
  • Live progress UIs — poll the trace while a job is processing to show what the agent is doing in real time. progress.reported events carry the run’s phase (planning, working, finalizing) with a human-readable message, and reasoning.summary events narrate the agent’s thinking.
  • Live browser view — pass ?liveView=true while a run is in flight to get activeBrowserSessions: the run’s active browser sessions, each with a liveViewUrl you can embed to watch (or demo) the agent browsing.
  • Cost trackingcreditsUsed reports credits consumed so far, capped at the run’s maxCredits if one was set.

How it works

Events are emitted by the run’s agents — the orchestrator 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

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

jobId
string<uuid>
required

The ID of the agent job

Query Parameters

liveView
enum<string>

If "true", include the currently active browser sessions with live view URLs.

Available options:
true,
false

Response

Successful response

success
boolean
id
string<uuid>
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; 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.

creditsUsed
number

Credits consumed so far, capped at maxCredits if one was set.

activeBrowserSessions
object[]

Currently active browser sessions (only present when liveView=true).