Execution trace of one agent turn

Assembles the trace of one agent turn (identified by its correlationId) for the agent’s editor: knowledge-base passages retrieved and their scores, tool calls, the chronology of what ran, errors, and the model, tokens, cost and latency of the turn (merged from the LLM Gateway). Step inputs and outputs are not included; fetch one on demand with GET /v1/agents/{agentId}/traces/{correlationId}/events/{eventId}.

Requires the agent-factory:traces:read org permission (or the agent-factory:* / * wildcards, or platform admin). Owning or editing the agent is not enough.

Caveats reported in the payload: retrieval is only populated for turns run from the editing surface, and summary.details_expired flags traces older than the 14-day cleanup of step details. The timeline is capped at 2000 events (summary.timeline_truncated).

GET /v1/agents/{agentId}/traces/{correlationId}

Execution trace of one agent turn

cURL

curl --request GET \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/traces/{correlationId} \
  --header 'Authorization: Bearer <token>'

200

{
  "correlationId": "<string>",
  "agent_id": "<string>",
  "summary": {
    "eventCount": 123,
    "errorCount": 123,
    "toolCallCount": 123,
    "retrievalCount": 123,
    "model": "<string>",
    "startTime": "2023-11-07T05:31:56Z",
    "endTime": "2023-11-07T05:31:56Z",
    "details_expired": true,
    "timeline_truncated": true,
    "workspaceId": "<string>"
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "cost": 123,
    "duration_ms": 123,
    "completions": 123
  },
  "retrieval": [
    {
      "query": "<string>",
      "tool_name": "<string>",
      "knowledge_base_id": "<string>",
      "status": "<string>",
      "returned": 123,
      "total_found": 123,
      "duplicates_filtered": 123,
      "passages": [
        {}
      ],
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ],
  "tool_calls": [
    {
      "type": "<string>",
      "tool_call_id": "<string>",
      "tool_name": "<string>",
      "display_name": "<string>",
      "status": "<string>",
      "error": null,
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ],
  "timeline": [
    {
      "id": "<string>",
      "workspaceId": "<string>",
      "timestamp": "2023-11-07T05:31:56Z",
      "startedAt": "2023-11-07T05:31:56Z",
      "type": "<string>",
      "automation": "<string>",
      "appInstance": "<string>"
    }
  ],
  "errors": [
    {
      "id": "<string>",
      "automation": "<string>",
      "appInstance": "<string>",
      "trigger": {},
      "error": null,
      "message": "<string>",
      "details": null,
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

BearerAuthOrgApiKeyAuth

Authorization · string · header · required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Headers

x-draft-mode · enum<string>

Resolve the agent as its editor does (draft configuration).

Available options: true

Path Parameters

agentId · string · required

Maximum string length: 64

correlationId · string · required

Maximum string length: 128

Query Parameters

excludeAutomation · string

Comma-separated automation slugs to leave out of the timeline. Defaults to _stream-event (one execution per streamed chunk). Send __none__ to keep every step.

Response

200

application/json

Assembled trace.

correlationId · string

agent_id · string

summary · object

Hide child attributes

summary. eventCount · integer

summary. errorCount · integer

summary. toolCallCount · integer

summary. retrievalCount · integer

summary. model · string

summary. startTime · string<date-time>

summary. endTime · string<date-time>

summary. details_expired · boolean

summary. timeline_truncated · boolean

summary. workspaceId · string

usage · object

Hide child attributes

usage. input_tokens · integer

usage. output_tokens · integer

usage. total_tokens · integer

usage. cost · number

usage. duration_ms · integer

usage. completions · integer

retrieval · object[]

Hide child attributes

retrieval. query · string

retrieval. tool_name · string

retrieval. knowledge_base_id · string

retrieval. status · string

retrieval. returned · integer

retrieval. total_found · integer

retrieval. duplicates_filtered · integer

retrieval. passages · object[]

retrieval. timestamp · string<date-time>

tool_calls · object[]

Hide child attributes

tool_calls. type · string

tool_calls. tool_call_id · string

tool_calls. tool_name · string

tool_calls. display_name · string

tool_calls. status · string

tool_calls. error · unknown

tool_calls. timestamp · string<date-time>

timeline · object[]

Projected steps (never raw payloads), sorted by emission time.

Hide child attributes

timeline. id · string

Event id, to pass to the step-detail endpoint.

timeline. workspaceId · string

timeline. timestamp · string<date-time>

timeline. startedAt · string<date-time>

timeline. type · string

timeline. automation · string

timeline. appInstance · string

errors · object[]

Hide child attributes

errors. id · string

errors. automation · string

errors. appInstance · string

errors. trigger · object

errors. error · unknown

errors. message · string

errors. details · unknown

errors. timestamp · string<date-time>