Retrieve AI Agent Logs by Repo

Before You Begin

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

Prerequisites

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

Step 1: Find Your Repo UUID

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

Step 2: Query AI Agent Logs

Use the aiAgentLogsByRepo query to retrieve a paginated list of AI agent execution logs for a specific pipe/table.

{
  aiAgentLogsByRepo(repoUuid: "pipe-uuid-123") {
    edges {
      node {
        uuid
        agentUuid
        agentName
        automationId
        automationName
        cardId
        cardTitle
        status
        createdAt
        updatedAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Available filters

The aiAgentLogsByRepo query accepts optional filters:

searchTerm: (Optional) Filter logs by a search term (minimum 3 characters). The search is applied to: agent name, behavior name, card title, and card ID (exact match when the term is numeric). Results matching any of these fields are returned.
status: (Optional) Filter logs by status. Available statuses include: success, failed, processing.

Example with search term

{
  aiAgentLogsByRepo(
    repoUuid: "pipe-uuid-123"
    searchTerm: "customer"
  ) {
    edges {
      node {
        uuid
        agentName
        cardTitle
        status
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Example with status filter

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

Example with both filters

{
  aiAgentLogsByRepo(
    repoUuid: "pipe-uuid-123"
    searchTerm: "error"
    status: failed
  ) {
    edges {
      node {
        uuid
        agentName
        cardTitle
        status
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Key Fields Explained

The aiAgentLogsByRepo query uses pagination. Refer to our Pagination basics page to understand more about how it works.

uuid: Log unique identifier.
agentUuid: UUID of the agent that executed.
agentName: Name of the agent.
automationId: ID of the automation that triggered the execution.
automationName: Name of the automation.
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 execution started.
updatedAt: When the execution was last updated.

Status Values

The status field can have the following values:

Processing statuses: processing
Final statuses: success, failed

Important Notes

Search Term: The searchTerm parameter requires at least 3 characters. Queries with fewer characters will be ignored.
Log Retention: Logs are available for the last 90 days by default.

Step 3: Execute and Interpret the Response

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

{
  "data": {
    "aiAgentLogsByRepo": {
      "edges": [
        {
          "node": {
            "uuid": "log-uuid-123",
            "agentUuid": "agent-uuid-123",
            "agentName": "Customer Support Agent",
            "automationId": "1",
            "automationName": "Respond to Customer",
            "cardId": "card-123",
            "cardTitle": "Customer Inquiry #1234",
            "status": "success",
            "createdAt": "2025-01-20T14:00:00Z",
            "updatedAt": "2025-01-20T14:00:15Z"
          }
        },
        {
          "node": {
            "uuid": "log-uuid-456",
            "agentUuid": "agent-uuid-123",
            "agentName": "Customer Support Agent",
            "automationId": "1",
            "automationName": "Respond to Customer",
            "cardId": "card-456",
            "cardTitle": "Customer Inquiry #5678",
            "status": "failed",
            "createdAt": "2025-01-20T15:00:00Z",
            "updatedAt": "2025-01-20T15:00:10Z"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "MQ"
      }
    }
  }
}

This query provides a quick and effective way to retrieve AI agent execution logs for a pipe/table with filtering and pagination support.