> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarmd.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a trace by correlation ID > **Security Requirements** | Auth Types | Entities | Permissions | Required Roles | |------------|----------|-------------|----------------| | USER | AUDIT | READ | AUDIT:READ | ## OpenAPI ````yaml /openapi/swarmd.json get /audit/v1/traces/{correlationId} openapi: 3.0.1 info: title: OpenAPI definition version: v0 servers: - url: https://api.swarmd.ai description: Production - url: https://api.sandbox.swarmd.ai description: Sandbox security: [] tags: - name: Policy Groups x-displayName: Policy Groups - name: Policy Bindings x-displayName: Policy Bindings - name: Webhooks x-displayName: Webhooks - name: Human JSON-RPC x-displayName: Human JSON-RPC - name: Channel JSON-RPC x-displayName: Channel JSON-RPC - name: HITL Approvals x-displayName: HITL Approvals - name: Agent JSON-RPC x-displayName: Agent JSON-RPC - name: Tasks x-displayName: Tasks - name: Push Notifications x-displayName: Push Notifications - name: Messaging x-displayName: Messaging - name: Conversations x-displayName: Conversations - name: Agent Discovery x-displayName: Agent Discovery - name: User Subscriptions x-displayName: User Subscriptions - name: MCP Servers x-displayName: MCP Servers - name: Kill Switches x-displayName: Kill Switches - name: Channels x-displayName: Channels - name: Channel Subscriptions x-displayName: Channel Subscriptions - name: Agents x-displayName: Agents - name: Agent Subscriptions x-displayName: Agent Subscriptions - name: Marketplace x-displayName: Marketplace - name: Identity Providers x-displayName: Identity Providers - name: Groups x-displayName: Groups - name: Authentication x-displayName: Authentication - name: Users x-displayName: Users - name: Tenants x-displayName: Tenants - name: Audit Integrity x-displayName: Audit Integrity - name: Audit Events x-displayName: Audit Events - name: Audit Traces x-displayName: Audit Traces - name: A2A Payments x-displayName: A2A Payments paths: /audit/v1/traces/{correlationId}: get: tags: - Audit Traces summary: Get a trace by correlation ID description: |- **Security Requirements** | Auth Types | Entities | Permissions | Required Roles | |------------|----------|-------------|----------------| | USER | AUDIT | READ | AUDIT:READ | operationId: getTrace parameters: - name: correlationId in: path required: true schema: type: string format: uuid responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/TraceResponse' security: - bearerAuth: [] components: schemas: TraceResponse: type: object properties: correlationId: type: string format: uuid tenantId: type: string format: uuid startTime: type: string format: date-time endTime: type: string format: date-time totalDurationMicros: type: integer format: int64 stepCount: type: integer format: int32 steps: type: array items: $ref: '#/components/schemas/TraceStepResponse' TraceStepResponse: type: object properties: eventId: type: string format: uuid auditType: type: string enum: - COMMUNICATION_AUDIT - VALIDATION_RESULT - X402_PAYMENT_REQUIRED - X402_PAYMENT_SUCCESS - X402_PAYMENT_ATTEMPT - X402_PAYMENT_REJECTED - REGEX_DETECTION - PRESIDIO_DETECTION - COMPREHEND_DETECTION - RATE_LIMIT - SKILL_RESTRICTION - HITL - HITL_GUARD - HITL_RESOLUTION - POLICY_LIFECYCLE transport: type: string enum: - REST - JSONRPC - GRPC - CHANNEL channelSource: type: string enum: - PLATFORM - TEAMS - SLACK auditAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR sentAt: type: string format: date-time durationMicros: type: integer format: int64 offsetMicros: type: integer format: int64 spanDurationMicros: type: integer format: int64 message: type: string sourceAgent: $ref: '#/components/schemas/AgentRef' sourceUser: $ref: '#/components/schemas/UserRef' sinkAgent: $ref: '#/components/schemas/AgentRef' sinkUser: $ref: '#/components/schemas/UserRef' channel: $ref: '#/components/schemas/ChannelRef' sinkChannel: $ref: '#/components/schemas/ChannelRef' payload: oneOf: - $ref: '#/components/schemas/AgentInteraction' - $ref: '#/components/schemas/ComprehendResult' - $ref: '#/components/schemas/HitlGuardResult' - $ref: '#/components/schemas/HitlResolutionResult' - $ref: '#/components/schemas/HitlResult' - $ref: '#/components/schemas/PolicyLifecycleResult' - $ref: '#/components/schemas/PresidioResult' - $ref: '#/components/schemas/RateLimitResult' - $ref: '#/components/schemas/RegexResult' - $ref: '#/components/schemas/SkillRestrictionResult' - $ref: '#/components/schemas/ValidationResult' - $ref: '#/components/schemas/X402PaymentAttemptResult' - $ref: '#/components/schemas/X402PaymentRejectedResult' - $ref: '#/components/schemas/X402PaymentResult' - $ref: '#/components/schemas/X402PaymentSuccessResult' metadata: $ref: '#/components/schemas/EventMetadata' contextId: type: string taskId: type: string messageId: type: string taskState: type: string stage: type: string AgentRef: type: object properties: id: type: string format: uuid name: type: string UserRef: type: object properties: id: type: string format: uuid name: type: string ChannelRef: type: object properties: id: type: string format: uuid name: type: string AgentInteraction: required: - method - stage - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 method: type: string stage: type: string httpStatus: type: integer format: int32 errorMessage: type: string errorCode: type: string requestBody: type: object additionalProperties: type: object requestHeaders: type: object additionalProperties: type: array items: type: string responseBody: type: object additionalProperties: type: object responseHeaders: type: object additionalProperties: type: array items: type: string taskState: type: string ComprehendResult: required: - languageCode - middlewareAction - policyId - policyLevel - policyName - policyVersion - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION entityType: type: string matchedValue: type: string confidenceScore: type: number format: float middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR errorMessage: type: string errorCode: type: string languageCode: type: string HitlGuardResult: required: - middlewareAction - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR taskId: type: string blockedSourceAgentId: type: string format: uuid blockedSourceUserId: type: string format: uuid policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION errorMessage: type: string errorCode: type: string HitlResolutionResult: required: - hitlRequestId - resolvedAction - resolvedBy - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 hitlRequestId: type: string format: uuid resolvedBy: type: string format: uuid resolvedAction: type: string resolutionMessage: type: string taskId: type: string contextId: type: string sourceAgentId: type: string format: uuid sourceUserId: type: string format: uuid agentMessageText: type: string policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION HitlResult: required: - middlewareAction - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR taskId: type: string contextId: type: string agentMessageRole: type: string agentMessageText: type: string detectionSource: type: string errorMessage: type: string errorCode: type: string PolicyLifecycleResult: required: - entityId - entityName - entityType - entityVersion - lifecycleAction - performedBy - reason - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 entityId: type: string format: uuid entityVersion: type: string entityName: type: string entityType: type: string enum: - POLICY - POLICY_GROUP - POLICY_BINDING - USER - GROUP - GROUP_MEMBERSHIP - CHANNEL - CHANNEL_SUBSCRIPTION - AGENT - AGENT_SUBSCRIPTION - USER_SUBSCRIPTION - MCP_SERVER - MCP_SUBSCRIPTION - KILL_SWITCH lifecycleAction: type: string enum: - DISABLED - ENABLED - CREATED - VERSION_CREATED - OWNERSHIP_TRANSFERRED - INVITED performedBy: type: string format: uuid reason: type: string replacedById: type: string format: uuid replacedByVersion: type: string replacedByName: type: string PresidioResult: required: - middlewareAction - policyId - policyLevel - policyName - policyVersion - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION entityType: type: string matchedValue: type: string confidenceScore: type: number format: double middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR errorMessage: type: string errorCode: type: string analyzerName: type: string scoreThreshold: type: number format: double RateLimitResult: required: - currentCount - limit - middlewareAction - policyId - policyLevel - policyName - policyVersion - remainingRequests - resetAtEpochMillis - strategyType - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION strategyType: type: string currentCount: type: integer format: int64 limit: type: integer format: int64 remainingRequests: type: integer format: int64 resetAtEpochMillis: type: integer format: int64 middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR errorMessage: type: string errorCode: type: string RegexResult: required: - middlewareAction - patternRegex - policyId - policyLevel - policyName - policyVersion - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION patternRegex: type: string matchedValue: type: string middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR errorMessage: type: string errorCode: type: string SkillRestrictionResult: required: - detectedToolCalls - middlewareAction - policyId - policyLevel - policyName - policyVersion - restrictionMode - stage - version - violatingSkills type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 policyId: type: string format: uuid policyVersion: type: string policyName: type: string policyLevel: type: string enum: - TENANT - AGENT - SUBSCRIPTION - CHANNEL - CHANNEL_SUBSCRIPTION restrictionMode: type: string detectedToolCalls: type: array items: type: string violatingSkills: type: array items: type: string stage: type: string middlewareAction: type: string enum: - LOG - MASK - BLOCK - WARN - HUMAN_REVIEW_REQUIRED - ERROR errorMessage: type: string errorCode: type: string ValidationResult: required: - endpoint - method - status - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 status: type: string enum: - SUCCESS - FAILURE method: type: string endpoint: type: string errorMessage: type: string errorCode: type: string X402PaymentAttemptResult: required: - stage - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 stage: type: string network: type: string scheme: type: string resource: type: string payer: type: string payee: type: string amount: type: string asset: type: string paymentPayload: type: object additionalProperties: type: object errorMessage: type: string errorCode: type: string X402PaymentRejectedResult: required: - httpStatus - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 httpStatus: type: integer format: int32 network: type: string scheme: type: string resource: type: string payer: type: string payee: type: string amount: type: string asset: type: string paymentPayload: type: object additionalProperties: type: object rejectionReason: type: string errorResponseBody: type: object additionalProperties: type: object errorMessage: type: string errorCode: type: string X402PaymentResult: required: - httpStatus - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 httpStatus: type: integer format: int32 maxAmountRequired: type: string payTo: type: string network: type: string asset: type: string scheme: type: string resource: type: string description: type: string mimeType: type: string maxTimeoutSeconds: type: integer format: int32 extra: type: object additionalProperties: type: object outputSchema: type: object additionalProperties: type: object errorMessage: type: string errorCode: type: string X402PaymentSuccessResult: required: - httpStatus - version type: object allOf: - $ref: '#/components/schemas/EventPayload' - type: object properties: version: type: integer format: int32 httpStatus: type: integer format: int32 network: type: string scheme: type: string resource: type: string payer: type: string payee: type: string amount: type: string asset: type: string transactionHash: type: string success: type: boolean paymentPayload: type: object additionalProperties: type: object settlementResponse: type: object additionalProperties: type: object errorMessage: type: string errorCode: type: string EventMetadata: required: - source - version type: object properties: version: type: integer format: int32 source: type: string EventPayload: type: object securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token (USER, AGENT, or SERVICE auth) ````