---
title: "List agents"
method: GET
path: "/agents"
tags: ["Agents"]
---

# List agents

`GET /agents`

Retrieve a paginated list of agents available to the authenticated user.

**Overview**

Returns agents accessible through direct, team, or org-level permissions.
Search is performed across agent name, description, and tags. Sorting and
pagination are applied by the AI backend and the resulting envelope is
forwarded unchanged by the Node gateway.

**Gateway contract**

The Node route supports only these query params: `page`, `limit`, `search`,
`sort_by`, and `sort_order`.

The Python backend also understands `isDeleted`, but this gateway route
does not forward it, so it is not part of the public API contract here.

## Query parameters

- `page` integer
- `limit` integer
- `search` string
- `sort_by` string
- `sort_order` 'asc' | 'desc'

## Response `200`

Paginated list of accessible agents.

- AgentListResponse — Paginated response returned by `GET /agents`. The Node gateway forwards the Python backend response on success. If the backend returns a non-200 response, the gateway still returns HTTP 200 with `success: true`, an empty `agents` array, and a zeroed pagination block derived from the requested `page` / `limit`.
  - `success` boolean, required
  - `agents` AgentListItem[], required
    - `_id` string, required — Full document id in the backing graph store.
    - `_key` string, required — Stable agent key used in route params.
    - `_rev` string — Backend document revision token.
    - `createdAtTimestamp` integer, required — Unix epoch timestamp in milliseconds when the agent was created.
    - `createdBy` string, required — MongoDB user ID of the agent creator
    - `description` string, nullable — Short human-readable description of the agent.
    - `instructions` string, nullable — Additional execution instructions stored on the agent.
    - `isActive` boolean, required — Whether the agent is active.
    - `isDeleted` boolean, required — Whether the agent has been soft-deleted.
    - `isServiceAccount` boolean, required — Whether this agent is a service-account agent.
    - `models` string[], required — Model entries configured on the agent. For `GET /agents`, the backend returns the stored normalized string representation, typically `modelKey_modelName`.
    - `name` string, required — Display name of the agent.
    - `startMessage` string, nullable — Greeting shown at conversation start.
    - `systemPrompt` string, nullable — System prompt stored on the agent.
    - `tags` string[], required — Free-form agent tags.
    - `updatedAtTimestamp` integer, required — Unix epoch timestamp in milliseconds when the agent was last updated.
    - `updatedBy` string, nullable — User id of the last updater, if present.
    - `webSearch` object, nullable — Web-search provider attachment for this agent, or `null` when none is attached. For `GET /agents`, the response formatter always emits `provider`. It may also emit `providerKey` and `providerLabel` when those values were present on the stored attachment. It does not emit `iconPath` on this response path.
      - `provider` string
      - `providerKey` string
      - `providerLabel` string
    - `shareWithOrg` boolean, required — Whether the agent is shared with the organization.
    - `toolsets` Toolset[], required — Toolset instances linked to the agent. Same projection as `GET /agents/{agentKey}`; the backend builds it from the graph edges for each agent on the returned page.
      - `_key` string — Toolset instance node key in the backing graph store.
      - `name` 'calendar' | 'clickup' | 'confluence' | 'drive' | 'github' | 'gmail' | 'jira' | 'lumos' | 'mariadb' | 'onedrive' | 'outlook' | 'redshift' | 'salesforce' | 'sharepoint' | 'slack' | 'teams' | 'zoom' — Registered toolset name (lowercase) accepted by the create-agent gateway.
      - `displayName` string — Human-readable toolset product label (for example `Jira` or `Slack`).
      - `type` string
      - `instanceId` string — Admin-created toolset instance id
      - `instanceName` string — Human-readable instance label (e.g. sidebar instance name)
      - `selectedTools` string[], nullable — Tool names explicitly selected for this toolset instance, when the instance was created with a subset selection. `null`/absent when the instance exposes all of the toolset's tools.
      - `tools` object[]
        - `_key` string — Tool node key in the backing graph store.
        - `name` string
        - `fullName` string
        - `toolsetName` string — Toolset type key the tool belongs to.
        - `description` string
        - `deprecated` boolean — Server-stamped on `GET /agents/{agentKey}`: `true` when the tool's `fullName` is no longer in the runtime tool registry (its `@tool` was removed). Read-only; ignored on create/update bodies. Not stamped on the `GET /agents` list projection.
    - `knowledge` Knowledge[], required — Knowledge connectors and indexed scopes linked to the agent. Same projection as `GET /agents/{agentKey}`; the backend builds it from the graph edges for each agent on the returned page.
      - `_key` string
      - `connectorId` string
      - `name` string
      - `type` string
      - `displayName` string
      - `filters` union — Knowledge scope filter as stored on the graph edge. The Node `getAgent` handler proxies this field unchanged from the AI service (only `agent.id` is stripped). May be a JSON string (typical graph storage) or an object. Prefer `filtersParsed` on GET for a guaranteed parsed object with the same keys as the object branch below.
        - AgentKnowledgeFiltersParsed — Indexed scope for a knowledge connector: record-group ids (collections / KB roots) and individual record ids. First-party create/update flows set `recordGroups` and `records`. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
          - `recordGroups` string[] — Record-group ids (e.g. knowledge-base roots) in scope.
          - `records` string[] — Individual record ids in scope.
        - string — JSON-encoded filter object (graph storage format).
      - `filtersParsed` AgentKnowledgeFiltersParsed — Indexed scope for a knowledge connector: record-group ids (collections / KB roots) and individual record ids. First-party create/update flows set `recordGroups` and `records`. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
        - `recordGroups` string[] — Record-group ids (e.g. knowledge-base roots) in scope.
        - `records` string[] — Individual record ids in scope.
    - `can_view` boolean, required — Effective permission to view the agent.
    - `can_share` boolean, required — Effective permission to share the agent.
    - `can_edit` boolean, required — Effective permission to edit the agent.
    - `can_delete` boolean, required — Effective permission to delete the agent.
    - `user_role` string, required — Effective role of the current user on this agent.
    - `access_type` string, required — How the user can access this agent.
  - `pagination` AgentListPagination, required — Pagination block returned by `GET /agents`.
    - `currentPage` integer, required — Current 1-based page number.
    - `limit` integer, required — Page size actually applied by the backend.
    - `totalItems` integer, required — Total number of matching agents across all pages.
    - `totalPages` integer, required — Total number of pages for the current query.
    - `hasNext` boolean, required — Whether a later page exists.
    - `hasPrev` boolean, required — Whether an earlier page exists.

## Other responses

- `400` — Validation failed for one or more query params.
- `401` — Unauthorized

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)