Execution trace of one agent turn

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/traces/{correlationId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/traces/{correlationId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Traces

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

agents

{agentId}

traces

{correlationId}

Execution trace of one agent turn

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/traces/{correlationId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/traces/{correlationId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Authorizations

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

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>

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Collections API

Execution trace of one agent turn

Authorizations

Headers

Path Parameters

Query Parameters

Response