Get Knowledge Base Data Lookup

Before You Begin

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

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: You must be admin of the pipe that owns the data lookup.
3. Pipe UUID: Identify the UUID of the pipe that owns the data lookup.
4. Data Lookup ID: Identify the UUID of the data lookup you want to retrieve. Use the List Knowledge Base Items query to find data lookup IDs.

See our Get resource IDs page for how to find these values.

Get a Knowledge Base Data Lookup

A knowledge base data lookup is an AI data source that performs live queries against records in another pipe. The aiKnowledgeBaseDataLookup query retrieves a single data lookup by its ID within a pipe, including its source pipe, search configuration, and output fields.

Inputs

• id: UUID of the knowledge base data lookup to retrieve (required).
• pipeUuid: UUID of the pipe that owns the data lookup (required).

Example: retrieve a knowledge base data lookup

query {
  aiKnowledgeBaseDataLookup(id: "c7d45e82-3a1f-4b96-8c2e-6f0d3a592b47", pipeUuid: "pipe-uuid-123") {
    id
    name
    description
    sourceRepoId
    searchQuery
    outputFields
    updatedAt
  }
}

Response:

{
  "data": {
    "aiKnowledgeBaseDataLookup": {
      "id": "c7d45e82-3a1f-4b96-8c2e-6f0d3a592b47",
      "name": "Customer Records",
      "description": "Looks up customer data from CRM pipe",
      "sourceRepoId": "d84f3b19-2c7e-4a50-9d1f-7e8c4b6a2d93",
      "searchQuery": "customer name",
      "outputFields": ["name", "email", "phone"],
      "updatedAt": "2025-01-15T14:00:00Z"
    }
  }
}

Response explained

• id: Unique identifier of the data lookup. Use this in update or delete operations.
• name: Display name of the data lookup.
• description: Short description of the data lookup's purpose.
• sourceRepoId: UUID of the pipe whose records are searched when the AI agent uses this data lookup.
• searchQuery: Free-text keyword used to match records in the source pipe.
• outputFields: List of field IDs whose values are returned from matching records and provided to the AI agent.
• updatedAt: When the data lookup was last updated.

Error handling

If the query fails (e.g., data lookup not found, permission denied, or pipe not found), you'll receive an error response:

{
  "data": {
    "aiKnowledgeBaseDataLookup": null
  },
  "errors": [
    {
      "message": "Pipe not found with id: pipe-uuid-123",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["aiKnowledgeBaseDataLookup"]
    }
  ]
}

Error response explained

• data.aiKnowledgeBaseDataLookup: Returns null when the operation fails.
• errors: Array containing error details when the operation fails.
• errors[].message: Human-readable error description. Common messages:
  • "Permission denied" — the authenticated user is not an admin of the pipe.
  • "Pipe not found with id: <uuid>" — the pipeUuid does not match an existing pipe.
  • "Record not found" — the data lookup id does not match any data lookup in the pipe.

Tips

• Source pipe access: The sourceRepoId must be a pipe accessible to the AI agent. Ensure the source pipe exists and contains the fields listed in outputFields.
• Listing data lookups: Use the List Knowledge Base Items query to find all data lookups for a pipe before fetching individual details.
• Managing data lookups: Use Create Knowledge Base Data Lookup, Update Knowledge Base Data Lookup, and Delete Knowledge Base Data Lookup to manage data lookups.