> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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`). ## OpenAPI ````yaml /api-reference/agent-factory/swagger.yml get /v1/agents/{agentId}/traces/{correlationId} openapi: 3.0.3 info: version: 1.0.0 title: Agent Factory API description: | Public REST API for the Agent Factory workspace - agents, conversations, messages, tools, artifacts, sharing, ratings, and discovery. Powered by Prisme.ai's runtime; all endpoints are exposed under each workspace's webhook namespace. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:agent-factory/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - OrgApiKeyAuth: [] tags: - name: Agents description: Agent CRUD, discovery, AGENTS.md import/export. - name: Access description: Agent access bindings, sharing, and access requests. - name: ApiKeys description: Agent-scoped API key management (mint, revoke, rotate). - name: Publishing description: Publish or discard draft changes on an agent. - name: Ratings description: User ratings on published agents. - name: Profiles description: >- Agent profiles/presets catalog (simple, workflow, agent_light, agent_full, orchestrator). - name: Activity description: Activity feed for agents (events, errors, lifecycle changes). - name: Analytics description: Agent usage analytics (series + summary). - name: Conversations description: Conversations on an agent (CRUD, archive, star). - name: Messages description: Send messages to an agent (synchronous send + SSE stream). - name: Tasks description: Async task lifecycle (list, fetch, cancel, resolve, subscribe). - name: Artifacts description: Generated artifacts (files, code, content) attached to a task. - name: Shares description: Conversation, message, and artifact share-link snapshots. - name: A2A description: Agent-to-agent JSON-RPC 2.0 gateway (well-known agent.json + RPC). - name: Tools description: Per-agent tool catalogue (system tools, MCP servers, function tools). - name: Retention description: Per-agent and org-wide conversation retention policies. - name: Traces description: >- Execution traces of agent turns (editor debugging, `agent-factory:traces:read`). - name: Evaluations description: Agent evaluation runs and results. - name: Admin description: | GDPR operations called by the AI Insights admin screens. They require elevated permissions: the caller must be a platform administrator (`platformRole` `superadmin` or `root`). The export route also lets a user export their own data. Each route is rate limited to 10 calls per hour per caller. paths: /v1/agents/{agentId}/traces/{correlationId}: get: tags: - Traces summary: Execution trace of one agent turn description: | 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`). operationId: getAgentTrace parameters: - name: agentId in: path required: true schema: type: string maxLength: 64 - name: correlationId in: path required: true schema: type: string maxLength: 128 - name: excludeAutomation in: query required: false schema: type: string description: | 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. - name: x-draft-mode in: header required: false schema: type: string enum: - 'true' description: Resolve the agent as its editor does (draft configuration). responses: '200': description: Assembled trace. content: application/json: schema: $ref: '#/components/schemas/AgentTrace' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - `agent-factory:traces:read` is required. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Agent not found, or no trace for this correlationId on this agent. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: The event store could not be read (`SEARCH_FAILED`). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: AgentTrace: type: object properties: correlationId: type: string agent_id: type: string summary: type: object properties: eventCount: type: integer errorCount: type: integer toolCallCount: type: integer retrievalCount: type: integer model: type: string startTime: type: string format: date-time endTime: type: string format: date-time details_expired: type: boolean timeline_truncated: type: boolean workspaceId: type: string usage: type: object properties: input_tokens: type: integer output_tokens: type: integer total_tokens: type: integer cost: type: number duration_ms: type: integer completions: type: integer retrieval: type: array items: type: object properties: query: type: string tool_name: type: string knowledge_base_id: type: string status: type: string returned: type: integer total_found: type: integer duplicates_filtered: type: integer passages: type: array items: type: object additionalProperties: true timestamp: type: string format: date-time tool_calls: type: array items: type: object properties: type: type: string tool_call_id: type: string tool_name: type: string display_name: type: string status: type: string error: nullable: true timestamp: type: string format: date-time timeline: type: array description: Projected steps (never raw payloads), sorted by emission time. items: type: object additionalProperties: true properties: id: type: string description: Event id, to pass to the step-detail endpoint. workspaceId: type: string timestamp: type: string format: date-time startedAt: type: string format: date-time type: type: string automation: type: string appInstance: type: string errors: type: array items: type: object properties: id: type: string automation: type: string appInstance: type: string trigger: type: object additionalProperties: true error: nullable: true message: type: string details: nullable: true timestamp: type: string format: date-time Error: type: object required: - error - message properties: error: type: string description: >- Stable PascalCase or SNAKE_CASE error code (e.g. AgentNotFound, VALIDATION_ERROR, FORBIDDEN, METHOD_NOT_ALLOWED). message: type: string description: Human-readable error message. details: type: object description: Optional structured context for the error. additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | 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 `. Org API keys (`iak_*`) are **not** accepted here - they carry no user identity. Use the `x-prismeai-api-key` header instead (see `OrgApiKeyAuth`). OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: | Organization API key (`iak_{orgSlug}_{uuid}`). Unlike `Authorization: Bearer`, this credential is **not** tied to a user identity - it is bound to the org and its effective access is defined by the scopes / permission rules attached to it (it can be restricted to a single project, or kept broader). For Agent Factory, these keys can be generated directly from the Agent Factory UI (in addition to the AI Governance settings). Send as `x-prismeai-api-key: iak_...`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.