--- title: "List agent conversations" method: GET path: "/agents/{agentKey}/conversations" tags: ["Agents"] --- # List agent conversations `GET /agents/{agentKey}/conversations` Paginated list of conversations for the agent (owned and shared-with-me), excluding archived threads. ## Path parameters - `agentKey` string, required ## Query parameters - `page` integer - `limit` integer - `sortBy` string - `sortOrder` string - `search` string - `startDate` string - `endDate` string - `status` string - `isArchived` 'true' | 'false' ## Response `200` Conversation list - AgentConversationListResponse — Envelope returned by `GET /agents/{agentKey}/conversations`. `conversations` contains rows owned by the caller for the agent; `sharedWithMeConversations` contains rows shared with the caller for the same agent. Both arrays use the same pagination and sort inputs, but `pagination.totalCount` and `totalPages` are computed only from `conversations` because the handler counts the owned-query filter only. - `conversations` AgentConversationListItem[], required - `_id` string, objectId - `agentKey` string — Agent identifier from the route path - `userId` string, objectId - `orgId` string, objectId - `title` string - `initiator` string, objectId - `status` 'None' | 'Inprogress' | 'Complete' | 'Failed' - `failReason` string - `modelInfo` ConversationModelInfo — AI model configuration recorded against a conversation or message. - `modelKey` string — Stable identifier of the configured model record - `modelName` string — Provider-facing model name (e.g. `gpt-4o-mini`) - `modelProvider` string — Provider key (e.g. `openai`, `anthropic`) - `modelFriendlyName` string — Human-readable display name - `chatMode` string — Chat mode used for this turn (e.g. `quick`, `internal_search`) - `isShared` boolean - `shareLink` string - `sharedWith` object[] - `userId` string, objectId - `accessLevel` 'read' | 'write' - `isArchived` boolean - `archivedBy` string, objectId, nullable - `archivedAt` string, date-time — Present on archived conversation endpoints. Derived from the document `updatedAt` timestamp when the archive response is built. - `isDeleted` boolean - `deletedBy` string, objectId, nullable - `conversationErrors` object[] - `message` string - `errorType` string - `timestamp` string, date-time - `messageId` string, objectId - `stack` string - `metadata` object - `conversationSource` 'agent_chat' - `lastActivityAt` integer — Epoch milliseconds of the latest activity on the thread - `createdAt` string, date-time - `updatedAt` string, date-time - `isOwner` boolean — Computed per request. `true` when the conversation `initiator` matches the authenticated user. - `accessLevel` 'read' | 'write' — Computed per request from `sharedWith`; defaults to `read` when no explicit share grant is attached to the serialized row. - `sharedWithMeConversations` AgentConversationListItem[], required - `_id` string, objectId - `agentKey` string — Agent identifier from the route path - `userId` string, objectId - `orgId` string, objectId - `title` string - `initiator` string, objectId - `status` 'None' | 'Inprogress' | 'Complete' | 'Failed' - `failReason` string - `modelInfo` ConversationModelInfo — AI model configuration recorded against a conversation or message. - `modelKey` string — Stable identifier of the configured model record - `modelName` string — Provider-facing model name (e.g. `gpt-4o-mini`) - `modelProvider` string — Provider key (e.g. `openai`, `anthropic`) - `modelFriendlyName` string — Human-readable display name - `chatMode` string — Chat mode used for this turn (e.g. `quick`, `internal_search`) - `isShared` boolean - `shareLink` string - `sharedWith` object[] - `userId` string, objectId - `accessLevel` 'read' | 'write' - `isArchived` boolean - `archivedBy` string, objectId, nullable - `archivedAt` string, date-time — Present on archived conversation endpoints. Derived from the document `updatedAt` timestamp when the archive response is built. - `isDeleted` boolean - `deletedBy` string, objectId, nullable - `conversationErrors` object[] - `message` string - `errorType` string - `timestamp` string, date-time - `messageId` string, objectId - `stack` string - `metadata` object - `conversationSource` 'agent_chat' - `lastActivityAt` integer — Epoch milliseconds of the latest activity on the thread - `createdAt` string, date-time - `updatedAt` string, date-time - `isOwner` boolean — Computed per request. `true` when the conversation `initiator` matches the authenticated user. - `accessLevel` 'read' | 'write' — Computed per request from `sharedWith`; defaults to `read` when no explicit share grant is attached to the serialized row. - `pagination` SemanticSearchHistoryPagination, required — Pagination block emitted by `buildPaginationMetadata` (utils.ts:417). `totalPages` is `Math.ceil(totalCount / limit)`, so an empty result has `totalPages: 0`, not `1`. - `page` integer, required - `limit` integer, required - `totalCount` integer, required - `totalPages` integer, required - `hasNextPage` boolean, required - `hasPrevPage` boolean, required - `filters` SemanticSearchHistoryFilters, required - `applied` SemanticSearchHistoryFiltersApplied, required — Echo of which filters the caller actually supplied, built by `buildFiltersMetadata` (utils.ts:430-486). `page` and `limit` always appear because they are normalised to defaults before being recorded, so `filters` is never empty and `values` always contains at least `{ page, limit }`. Other keys appear only when the matching query param was non-empty (or, for `dateRange`, when `createdAt` was set on the Mongo filter). `values` keys are scalar strings rather than typed primitives (`'true'`/`'false'`, `'5'`, etc.) because they are passed through from `req.query` as Express parsed them — only `page` and `limit` are coerced to integers via `safeParsePagination`. - `filters` string[], required - `values` object, required - `page` integer - `limit` integer - `search` string - `shared` string - `tags` string - `minMessages` string - `sortBy` string - `sortOrder` string - `startDate` string - `endDate` string - `messageType` string - `dateRange` SemanticSearchHistoryAppliedDateRange — Echoed back only when the caller passed `startDate` and/or `endDate`. Each bound is an ISO 8601 string when set; the field is absent when the corresponding query param was omitted (utils.ts:480-486 reads `appliedFilters.createdAt.$gte?.toISOString()` directly, so missing bounds become `undefined` and drop out of the JSON). - `start` string, date-time - `end` string, date-time - `available` SemanticSearchHistoryFiltersAvailable, required — Catalogue of filters the endpoint supports, plus their current values and `applied` flags. Built by `buildFiltersMetadata` (utils.ts:430-624). - `shared` SemanticSearchHistoryFilterToggle, required — Generic "filter X is available, current value is Y" block used for `shared`, `tags`, `minMessages`, `search`, and `messageType`. Either `type` (free-form value) or `values` (enum of allowed strings) is present, not both. `current` is the caller-supplied value passed through from `req.query`, hence string-or-null even when `type` is `'number'`. - `type` string - `values` string[] - `description` string, required - `current` string, nullable, required - `applied` boolean, required - `tags` SemanticSearchHistoryFilterToggle, required — Generic "filter X is available, current value is Y" block used for `shared`, `tags`, `minMessages`, `search`, and `messageType`. Either `type` (free-form value) or `values` (enum of allowed strings) is present, not both. `current` is the caller-supplied value passed through from `req.query`, hence string-or-null even when `type` is `'number'`. - `type` string - `values` string[] - `description` string, required - `current` string, nullable, required - `applied` boolean, required - `minMessages` SemanticSearchHistoryFilterToggle, required — Generic "filter X is available, current value is Y" block used for `shared`, `tags`, `minMessages`, `search`, and `messageType`. Either `type` (free-form value) or `values` (enum of allowed strings) is present, not both. `current` is the caller-supplied value passed through from `req.query`, hence string-or-null even when `type` is `'number'`. - `type` string - `values` string[] - `description` string, required - `current` string, nullable, required - `applied` boolean, required - `search` SemanticSearchHistoryFilterToggle, required — Generic "filter X is available, current value is Y" block used for `shared`, `tags`, `minMessages`, `search`, and `messageType`. Either `type` (free-form value) or `values` (enum of allowed strings) is present, not both. `current` is the caller-supplied value passed through from `req.query`, hence string-or-null even when `type` is `'number'`. - `type` string - `values` string[] - `description` string, required - `current` string, nullable, required - `applied` boolean, required - `pagination` object, required - `page` SemanticSearchHistoryPaginationField, required - `type` string, required - `current` integer, required - `min` integer, required - `max` integer, required - `default` integer, required - `description` string, required - `applied` boolean, required - `limit` SemanticSearchHistoryPaginationField, required - `type` string, required - `current` integer, required - `min` integer, required - `max` integer, required - `default` integer, required - `description` string, required - `applied` boolean, required - `sorting` object, required - `sortBy` SemanticSearchHistorySortField, required — Used for `available.sorting.{sortBy,sortOrder}` and `available.sortingMessages.{sortBy,sortOrder}`. The `applied` flag is present on `sorting.*` and absent on `sortingMessages.*`, so it is optional here. - `values` string[], required - `default` string, required - `description` string, required - `current` string, required - `applied` boolean - `sortOrder` SemanticSearchHistorySortField, required — Used for `available.sorting.{sortBy,sortOrder}` and `available.sortingMessages.{sortBy,sortOrder}`. The `applied` flag is present on `sorting.*` and absent on `sortingMessages.*`, so it is optional here. - `values` string[], required - `default` string, required - `description` string, required - `current` string, required - `applied` boolean - `dateFilters` object, required - `dateRange` SemanticSearchHistoryDateRange, required - `type` string, required - `description` string, required - `format` string, required - `current` object, required - `start` string, nullable, required - `end` string, nullable, required - `applied` boolean, required - `messageFilters` object, required - `messageType` SemanticSearchHistoryFilterToggle, required — Generic "filter X is available, current value is Y" block used for `shared`, `tags`, `minMessages`, `search`, and `messageType`. Either `type` (free-form value) or `values` (enum of allowed strings) is present, not both. `current` is the caller-supplied value passed through from `req.query`, hence string-or-null even when `type` is `'number'`. - `type` string - `values` string[] - `description` string, required - `current` string, nullable, required - `applied` boolean, required - `sortingMessages` object, required - `sortBy` SemanticSearchHistorySortField, required — Used for `available.sorting.{sortBy,sortOrder}` and `available.sortingMessages.{sortBy,sortOrder}`. The `applied` flag is present on `sorting.*` and absent on `sortingMessages.*`, so it is optional here. - `values` string[], required - `default` string, required - `description` string, required - `current` string, required - `applied` boolean - `sortOrder` SemanticSearchHistorySortField, required — Used for `available.sorting.{sortBy,sortOrder}` and `available.sortingMessages.{sortBy,sortOrder}`. The `applied` flag is present on `sorting.*` and absent on `sortingMessages.*`, so it is optional here. - `values` string[], required - `default` string, required - `description` string, required - `current` string, required - `applied` boolean - `meta` SemanticSearchHistoryMeta, required — `requestId` comes from `req.context?.requestId` and is omitted from the JSON when upstream middleware did not set it. - `requestId` string - `timestamp` string, date-time, required - `duration` integer, required ## Other responses - `400` — Invalid path or query parameter. This includes Zod validation failures such as invalid pagination, invalid booleans, malformed date values, duplicate `search` parameters, or overlong / invalid `search` input. - `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)