Retrieve AI Agent Logs by Repo

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. 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
        trigger
        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.
• triggers: (Optional) Filter logs by the automation event that started them. Accepts a list, and a log is returned when its trigger matches any entry. Passing an empty list returns no logs.
• createdAt: (Optional) Filter logs by when they were created, using from and to. Both bounds are optional and inclusive, so you can send only one of them.

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
    }
  }
}

Example with trigger filter

{
  aiAgentLogsByRepo(
    repoUuid: "pipe-uuid-123"
    triggers: [card_created, field_updated]
  ) {
    edges {
      node {
        uuid
        agentName
        trigger
        status
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Example with date filter

{
  aiAgentLogsByRepo(
    repoUuid: "pipe-uuid-123"
    createdAt: { from: "2025-01-20T00:00:00Z", to: "2025-01-21T00:00:00Z" }
  ) {
    edges {
      node {
        uuid
        agentName
        trigger
        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).
• trigger: Automation event that started the execution, for example card_created or field_updated.
• 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

Trigger Values

The trigger field and the triggers filter accept the automation events: card_created, card_moved, card_left_phase, field_updated, card_inbox_received_email, all_children_in_phase, sla_based, scheduler, http_response_received, and manually_triggered.

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.
• Date Filter and Retention: createdAt narrows the 90 day retention window, it does not extend it. A from older than 90 days returns only what the window still holds.
• Date Filter Bounds: Sending a from later than the to returns an error rather than an empty list.

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",
            "trigger": "card_created",
            "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",
            "trigger": "field_updated",
            "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.