Retrieve AI Agent Log Details

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: You must be admin of the pipe/table.
3. Feature Toggle: The organization must have AI Agents feature enabled via toggle.
4. Log UUID: Identify the execution log UUID to retrieve details from.

Step 1: Find Your Log UUID

See our Get resource IDs page for how to find the pipe UUID.

Via GraphQL Query

• Use the aiAgentLogsByRepo query to list logs and find the UUID:

{
  aiAgentLogsByRepo(repoUuid: "pipe-uuid-123") {
    edges {
      node {
        uuid
        agentName
        status
        createdAt
      }
    }
  }
}

Step 2: Query AI Agent Log Details

Use the aiAgentLogDetails query to retrieve detailed information about a specific AI agent behavior execution log.

{
  aiAgentLogDetails(uuid: "log-uuid-123") {
    uuid
    agentUuid
    agentName
    automation {
      id
      name
    }
    cardId
    cardTitle
    status
    createdAt
    finishedAt
    executionTime
    tracingNodes {
      nodeName
      status
      credits
      message
    }
  }
}

Key Fields Explained

• uuid: Log unique identifier.
• agentUuid: UUID of the agent that executed.
• agentName: Name of the agent.
• automation: Automation that triggered the AI agent behavior execution.
• cardId: ID of the card/record involved (if any).
• cardTitle: Title of the card/record involved (if any).
• status: Status of the execution (processing, success, failed).
• createdAt: When the log was created.
• finishedAt: When the execution success (null if still processing).
• executionTime: Execution time in seconds.
• tracingNodes: Tracing nodes of the AI agent behavior execution, showing the execution flow and any errors.
  • nodeName: Name of the step.
  • status: Outcome of the step.
  • credits: AI credits the step consumed. Null when the execution predates credit reporting, or when the log is served from the fallback described below.
  • message: Reasoning or error text for the step. Null for executions served with credit data.

Status Values

The status field can have the following values:

• Processing statuses: processing
• Final statuses: success, failed

Note: Tracing nodes are only available for completed executions (not for processing statuses).

Credits and message

credits and message are not both populated on the same node. The tracing nodes of a completed
execution are read from the agent execution service, which reports each step's name, outcome and
credit consumption but no reasoning text, so message is null there.

When that service has no record of an execution, the log falls back to the copy stored with the
automation. That copy carries the reasoning text but no credit data, so message is populated and
credits is null. Older executions are typically served this way.

Step 3: Execute and Interpret the Response

After running the query, you'll receive a structured JSON response. Here's an example:

{
  "data": {
    "aiAgentLogDetails": {
      "uuid": "log-uuid-123",
      "agentUuid": "agent-uuid-123",
      "agentName": "Customer Support Agent",
      "automation": {
        "id": "1",
        "name": "Respond to Customer"
      },
      "cardId": "card-123",
      "cardTitle": "Customer Inquiry #1234",
      "status": "success",
      "createdAt": "2025-01-20T14:00:00Z",
      "finishedAt": "2025-01-20T14:00:15Z",
      "executionTime": 15.0,
      "tracingNodes": [
        {
          "nodeName": "Execution Plan",
          "status": "SUCCESS",
          "credits": 2.0,
          "message": null
        },
        {
          "nodeName": "Respond to Customer",
          "status": "SUCCESS",
          "credits": 1.5,
          "message": null
        }
      ]
    }
  }
}

For processing statuses, the response might look like:

{
  "data": {
    "aiAgentLogDetails": {
      "uuid": "log-uuid-456",
      "agentUuid": "agent-uuid-123",
      "agentName": "Customer Support Agent",
      "automation": {
        "id": "1",
        "name": "Respond to Customer"
      },
      "cardId": "card-456",
      "cardTitle": "Customer Inquiry #5678",
      "status": "processing",
      "createdAt": "2025-01-20T15:00:00Z",
      "finishedAt": null,
      "executionTime": null,
      "tracingNodes": []
    }
  }
}

This query provides detailed information about a specific AI agent execution, including the execution flow and any errors that occurred.