> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4orfll.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Obtenir la trace d’exécution d’un agent
Chaque exécution d’agent enregistre une **trace d’exécution** canonique : un flux ordonné d’événements décrivant tout ce qu’elle a fait — les outils qu’elle a appelés et leurs résultats, des résumés de raisonnement, des mises à jour de progression, des sessions de navigateur et des modifications de ses artefacts de sortie. Il s’agit du même flux d’événements qui alimente la vue Activité en direct dans l’[Agent Playground](https://www.firecrawl.dev/app/agent).
## À quoi cela sert
* **Débogage des exécutions** — consultez les recherches, scrapes et extractions exacts effectués par l’agent, les entrées (`tool_call.started`) et résultats (`tool_call.finished`) de chaque outil, ainsi que l’étape à laquelle une exécution a échoué (`error.occurred`, ainsi que l’`outcome` et l’`error` structuré de l’événement terminal `run.finished`).
* **Interfaces de suivi en direct** — interrogez la trace pendant qu’une tâche d’agent est en `processing` afin d’afficher en temps réel ce que fait l’agent. Les événements `progress.reported` indiquent la phase de l’exécution (`planning`, `working`, `finalizing`) avec un message lisible par un humain, et les événements `reasoning.summary` décrivent le raisonnement de l’agent.
* **Vue Browser en direct** — ajoutez `?liveView=true` pendant qu’une exécution est en cours pour obtenir `activeBrowserSessions` : les sessions de navigateur actives de l’exécution, chacune avec une `liveViewUrl` que vous pouvez intégrer pour observer (ou présenter) la navigation de l’agent.
* **Suivi des coûts** — `creditsUsed` indique les crédits consommés jusqu’à présent, plafonnés à `maxCredits` pour l’exécution si cette valeur a été définie.
## Fonctionnement
Les événements sont émis par les agents de l’exécution — l’`orchestrator` et ses `subagent`s — et chacun identifie son émetteur dans le champ `agent`. Les opérations du Browser s’effectuent dans la session de navigateur propre à l’agent et sont signalées via des événements `browser.session.*`, et non par des agents de navigateur distincts. Triez les événements selon `producerSequence` (pour chaque agent émetteur). Le champ `type` distingue les 13 variantes d’événements ; consultez le schéma de réponse ci-dessous pour obtenir la liste complète et les champs de chaque variante.
Les événements `artifact.updated` ne contiennent pas le contenu de l’artefact lui-même : ils y font référence via `snapshotId`, que vous récupérez avec le [point de terminaison de snapshot](/fr/api-reference/endpoint/agent-snapshot).
Des événements peuvent continuer à arriver pendant un court instant après la réception de `run.finished`. Si vous interrogez une exécution en cours, maintenez une courte fenêtre de délai avant d’afficher l’état final.
Les traces sont enregistrées pour les exécutions Spark 2, c’est-à-dire toutes les nouvelles exécutions. Les tâches d’agent démarrées sur des modèles Spark 1 avant leur retrait ne disposent d’aucune trace et renvoient `400`.
> Êtes-vous un agent IA ayant besoin d’une clé API Firecrawl ? Consultez [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour les instructions d’intégration automatisée.
## OpenAPI
````yaml fr/api-reference/v2-openapi.json GET /agent/{jobId}/trace
openapi: 3.0.0
info:
contact:
email: support@firecrawl.dev
name: Firecrawl Support
url: https://firecrawl.dev/support
description: >-
API pour interagir avec les services Firecrawl afin d’effectuer des tâches
de scraping et de crawling web.
title: Firecrawl API
version: v2
servers:
- url: https://api.firecrawl.dev/v2
security:
- bearerAuth: []
paths:
/agent/{jobId}/trace:
parameters:
- description: L’ID de la tâche d’agent
in: path
name: jobId
required: true
schema:
format: uuid
type: string
get:
tags:
- Agent
summary: Obtenir la trace d’exécution d’une tâche d’agent
operationId: getAgentTrace
parameters:
- description: "Si «\_true\_», inclure les sessions de navigateur actuellement actives avec les URL de vue en direct."
in: query
name: liveView
required: false
schema:
enum:
- 'true'
- 'false'
type: string
responses:
'200':
content:
application/json:
schema:
properties:
activeBrowserSessions:
description: >-
Sessions de navigateur actuellement actives (présentes
uniquement lorsque liveView=true).
items:
properties:
id:
type: string
liveViewUrl:
type: string
viewport:
properties:
height:
type: number
width:
type: number
type: object
type: object
type: array
creditsUsed:
description: >-
Crédits consommés jusqu’à présent, plafonnés à maxCredits
si cette valeur a été définie.
type: number
events:
description: "Événements d’exécution canoniques pour l’exécution\_; classés selon producerSequence. Les événements artifact.updated contiennent les valeurs snapshotId utilisées par le point de terminaison des instantanés."
items:
$ref: '#/components/schemas/AgentTraceEvent'
type: array
id:
format: uuid
type: string
success:
type: boolean
type: object
description: Réponse réussie
'400':
content:
application/json:
schema:
properties:
error:
example: Trace is only available for Spark 2 extracts
type: string
type: object
description: >-
Requête incorrecte — l’ID de tâche n’est pas un UUID valide ou la
tâche ne s’est pas exécutée sur spark-2 (les traces sont disponibles
uniquement pour les tâches d’agent spark-2).
'404':
content:
application/json:
schema:
properties:
error:
example: Agent job not found
type: string
type: object
description: Tâche d’agent introuvable
security:
- bearerAuth: []
components:
schemas:
AgentTraceEvent:
description: "Événement d’exécution canonique issu d’une exécution d’agent. Chaque événement contient les champs d’enveloppe schemaVersion, eventId, runId, occurredAt, producerSequence et agent\_; le champ type distingue la variante. Les événements usage.recorded sont internes et ne sont jamais exposés, et les événements agent.started omettent le champ model."
discriminator:
propertyName: type
oneOf:
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis au démarrage de l’exécution.
enum:
- run.started
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
title: run.started
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
reason:
enum:
- user
type: string
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: >-
Émis lorsqu’une annulation est demandée (via DELETE
/agent/{jobId}).
enum:
- run.cancel_requested
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- reason
title: run.cancel_requested
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
error:
allOf:
- $ref: '#/components/schemas/AgentTraceError'
description: "null lorsque le résultat est succeeded\_; sinon, l’erreur structurée."
nullable: true
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
- credit_limit_reached
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Événement terminal de l’exécution.
enum:
- run.finished
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- outcome
- error
title: run.finished
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’un agent (orchestrateur ou sous-agent) démarre.
enum:
- agent.started
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
title: agent.started
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
durationMs:
type: integer
error:
allOf:
- $ref: '#/components/schemas/AgentTraceError'
description: "null lorsque le résultat est succeeded\_; sinon, l’erreur structurée."
nullable: true
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’un agent termine son exécution.
enum:
- agent.finished
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- outcome
- durationMs
- error
title: agent.finished
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Émis au démarrage d’une session de navigateur.
enum:
- browser.session.started
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- sessionId
title: browser.session.started
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
durationMs:
type: integer
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Émis lorsqu’une session de navigateur se termine.
enum:
- browser.session.finished
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- sessionId
- durationMs
title: browser.session.finished
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
message:
type: string
occurredAt:
format: date-time
type: string
phase:
enum:
- planning
- working
- finalizing
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsque l’orchestrateur signale une progression.
enum:
- progress.reported
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- phase
- message
title: progress.reported
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
text:
type: string
type:
description: Résumé du raisonnement de l’agent.
enum:
- reasoning.summary
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- text
title: reasoning.summary
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
parameters:
description: L’entrée transmise à l’outil (JSON arbitraire).
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Émis au démarrage d’un appel d’outil.
enum:
- tool_call.started
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- toolCallId
- toolName
- parameters
title: tool_call.started
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
result:
description: Le résultat renvoyé par l’outil (JSON arbitraire).
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Émis lorsqu’un appel d’outil se termine.
enum:
- tool_call.finished
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- toolCallId
- toolName
- result
title: tool_call.finished
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
artifact:
$ref: '#/components/schemas/AgentTraceArtifact'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’un artefact de sortie est modifié.
enum:
- artifact.updated
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- artifact
title: artifact.updated
type: object
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
error:
$ref: '#/components/schemas/AgentTraceError'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’une erreur non fatale survient durant l’exécution.
enum:
- error.occurred
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- error
title: error.occurred
type: object
AgentTraceAgent:
description: Identité de l’agent ayant émis l’événement.
properties:
id:
format: uuid
type: string
name:
type: string
parentId:
description: ID de l’agent parent (présent pour les sous-agents).
format: uuid
type: string
role:
enum:
- orchestrator
- subagent
- system
type: string
required:
- id
- role
- name
type: object
AgentTraceError:
description: Erreur structurée associée aux événements terminaux et d’erreur.
properties:
code:
enum:
- cancelled
- credit_limit_reached
- parent_finished
- refused
- internal
type: string
message:
type: string
retryable:
type: boolean
source:
enum:
- agent
- tool
- billing
- system
type: string
required:
- code
- source
- retryable
- message
type: object
AgentTraceArtifact:
description: Descripteur d’une modification apportée à un artefact de sortie.
properties:
artifactId:
type: string
change:
enum:
- init
- partial
- append
- modify
- update
type: string
changedFields:
items:
type: string
type: array
itemCount:
type: integer
kind:
enum:
- json
- markdown
- html
- screenshot
- text
type: string
path:
description: >-
Chemin de l’artefact dans l’espace de travail, par ex.
/workspace/data.json.
type: string
snapshotId:
description: >-
Utilisez GET /agent/{jobId}/snapshots/{snapshotId} pour récupérer le
contenu de cet instantané.
format: uuid
type: string
sourceToolCallId:
description: L’appel d’outil ayant produit cette modification, le cas échéant.
type: string
required:
- kind
- artifactId
- snapshotId
- change
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````