Get Agent Trace

2 min read

get/agent/{jobId}/trace

Request example

curl --request GET \
  --url https://api.firecrawl.dev/v2/agent/{jobId}/trace \
  --header 'Authorization: Bearer <token>'

Response

{
  "success": true,
  "id": "<string>",
  "events": [
    {
      "schemaVersion": 1,
      "eventId": "<string>",
      "runId": "<string>",
      "occurredAt": "2026-08-10T12:00:00Z",
      "producerSequence": 1,
      "agent": {
        "id": "<string>",
        "role": "orchestrator",
        "name": "<string>",
        "parentId": "<string>"
      },
      "type": "run.started"
    }
  ],
  "creditsUsed": 1,
  "activeBrowserSessions": [
    {
      "id": "<string>",
      "liveViewUrl": "<string>",
      "viewport": {
        "width": 1,
        "height": 1
      }
    }
  ]
}

get/agent/{jobId}/trace

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 tracking — creditsUsed 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.

Note

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.

Authorization

Authorizationstringheaderrequired#

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

Path parameters

jobIdstringrequired#

The ID of the agent job

Query parameters

liveViewenum<string>#

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

Options:truefalse

Responses

application/json

Successful response

successboolean#

idstring#

eventsobject[]#

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.

Show child attributes

One of

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when the run starts.

Options:run.started

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when cancellation is requested (via DELETE /agent/{jobId}).

Options:run.cancel_requested

reasonenum<string>required#

Options:user

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Terminal event for the run.

Options:run.finished

outcomeenum<string>required#

Options:succeededfailedcancelledrefusedcredit_limit_reached

errorobjectrequired#

Structured error attached to terminal and error events.

Show child attributes

codeenum<string>required#

Options:cancelledcredit_limit_reachedparent_finishedrefusedinternal

sourceenum<string>required#

Options:agenttoolbillingsystem

retryablebooleanrequired#

messagestringrequired#

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when an agent (orchestrator or subagent) starts.

Options:agent.started

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when an agent finishes.

Options:agent.finished

outcomeenum<string>required#

Options:succeededfailedcancelledrefused

durationMsintegerrequired#

errorobjectrequired#

Structured error attached to terminal and error events.

Show child attributes

codeenum<string>required#

Options:cancelledcredit_limit_reachedparent_finishedrefusedinternal

sourceenum<string>required#

Options:agenttoolbillingsystem

retryablebooleanrequired#

messagestringrequired#

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when a browser session starts.

Options:browser.session.started

sessionIdstringrequired#

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when a browser session finishes.

Options:browser.session.finished

sessionIdstringrequired#

durationMsintegerrequired#

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when the orchestrator reports progress.

Options:progress.reported

phaseenum<string>required#

Options:planningworkingfinalizing

messagestringrequired#

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

A summary of the agent's reasoning.

Options:reasoning.summary

textstringrequired#

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when a tool call starts.

Options:tool_call.started

toolCallIdstringrequired#

toolNamestringrequired#

parametersanyrequired#

The input passed to the tool (arbitrary JSON).

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when a tool call finishes.

Options:tool_call.finished

toolCallIdstringrequired#

toolNamestringrequired#

resultanyrequired#

The result returned by the tool (arbitrary JSON).

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when an output artifact changes.

Options:artifact.updated

artifactobjectrequired#

Descriptor for a change to an output artifact.

Show child attributes

kindenum<string>required#

Options:jsonmarkdownhtmlscreenshottext

artifactIdstringrequired#

pathstring#

Workspace path of the artifact, e.g. /workspace/data.json.

snapshotIdstringrequired#

Pass to GET /agent/{jobId}/snapshots/{snapshotId} to fetch this snapshot's content.

changeenum<string>required#

Options:initpartialappendmodifyupdate

changedFieldsstring[]#

itemCountinteger#

sourceToolCallIdstring#

The tool call that produced this change, when applicable.

schemaVersionenum<integer>required#

Options:1

eventIdstringrequired#

Unique ID of this event.

runIdstringrequired#

The agent job ID this event belongs to.

occurredAtstringrequired#

producerSequenceintegerrequired#

Monotonic sequence number from the emitting agent; order events by it.

agentobjectrequired#

Identity of the agent that emitted the event.

Show child attributes

idstringrequired#

roleenum<string>required#

Options:orchestratorsubagentsystem

namestringrequired#

parentIdstring#

ID of the parent agent (present on subagents).

typeenum<string>required#

Emitted when a non-fatal error occurs during the run.

Options:error.occurred

errorobjectrequired#

Structured error attached to terminal and error events.

Show child attributes

codeenum<string>required#

Options:cancelledcredit_limit_reachedparent_finishedrefusedinternal

sourceenum<string>required#

Options:agenttoolbillingsystem

retryablebooleanrequired#

messagestringrequired#

creditsUsednumber#

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

activeBrowserSessionsobject[]#

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

Show child attributes

idstring#

liveViewUrlstring#

viewportobject#

Show child attributes

widthnumber#

heightnumber#

Get Agent Status Get Agent Snapshot