Skip to main content
Fetch one discussion with discussion(discussionId:), or a page of them with discussions. threadDiscussion(threadDiscussionId:) still resolves. Prefer discussion for a new integration. Discussion IDs use the thd_ prefix.
For TypeScript, the GraphQL SDK gives you a fully typed client for these operations.
These operations require the following permissions:
  • threadDiscussion:read to fetch discussion and discussions
  • threadDiscussionMessage:read to fetch messages

List discussions

discussions takes filters, sortBy, first, and after. Sort with sortBy: field is CREATED_AT, LAST_ACTIVITY_AT, or UPDATED_AT, and direction is ASC or DESC. filters accepts:
  • statuses: OPEN or RESOLVED
  • agentStatuses: UNKNOWN, IDLE, IN_PROGRESS, TOOL_CALL_APPROVAL_PENDING, or CONNECTION_PENDING. A resolved discussion keeps the agent status it had when it was resolved.
  • threadIds: discussions on those threads, including workflow tasks when isWorkflowTask is unset
  • createdByUserIds: the user who created the discussion
  • participatedByUserIds: a user who has posted a message in it
  • discussionTypes: EMAIL, SLACK, CURSOR_WORKSPACE_BACKGROUND_AGENT, or AGENT_SESSION
  • agentTypes: PLAIN_SIDEKICK, or CUSTOM_AGENT for an agent you connect
  • agentMachineUserIds: discussions run by those agent machine users
  • isUnread: unread agent responses when true, read ones when false
  • createdBySystem: discussions a system actor created, such as a workflow, when true
  • isWorkflowTask: Sidekick Agent tasks started by an ask_sidekick workflow step when true. Pass false to leave those tasks out.
  • sourceEntityIds: discussions started from those entities
  • sourceEntityTypes: the entity type for sourceEntityIds
  • sourcePageLinks: the page the discussion was started from
  • lastActivityAtAfter and lastActivityAtBefore: ISO 8601 bounds on the latest message
  • and, or, not: combine the filters above
discussions with threadIds and no isWorkflowTask filter includes workflow tasks. Thread.threadDiscussions returns the discussions on that thread and leaves workflow tasks out.
Query
Variables

Get a discussion by ID

discussion loads one discussion, including its messages. Select visibility to see who can open it: WORKSPACE is every user in the workspace, and USER is the user who created it. The field is null until set.
Query
Variables

Messages

messages returns the discussion’s messages. Pass first, after, last, or before to page through them. Each message includes text, createdBy, entryType, entry, attachments, and workspaceFiles. attachments is for email, Slack, and Cursor messages. workspaceFiles is for Sidekick Agent session messages. entry is one of seven payloads. entryType names which one you received:
  • ThreadDiscussionMessageEntryPayload: the message body
  • ThreadDiscussionToolCallEntryPayload: a tool call
  • ThreadDiscussionApprovalRequestEntryPayload: a Sidekick Agent approval
  • ThreadDiscussionToolCallApprovalEntryPayload: an approval on one tool call an agent reported
  • ThreadDiscussionConnectRequestEntryPayload: a request to connect a Sidekick Agent tool
  • ThreadDiscussionQuestionEntryPayload: a Sidekick Agent question card
  • ThreadDiscussionTurnStoppedEntryPayload: a stopped turn
A tool-call payload has toolCallId, service, op, description, args, status, error, durationMs, and response. status is PENDING, then SUCCESS or ERROR. toolCallId is null on a Sidekick Agent call. service is null on a call an agent reported. response is the JSON-encoded result of a successful Sidekick Agent write. It is null for a read, a failed call, an oversized result, and a call an agent reported.

What the Sidekick Agent reads

The Sidekick Agent reads discussions with three tools. discussion.get returns metadata for one discussion. discussion.list returns a list of discussions. discussion.messages returns message text, authors, and files. Each tool returns null when the discussion is missing or inaccessible. It also returns null when the linked thread is not readable, or when visibility is USER and the sender is not the creator. thread.timeline returns discussion entry metadata. Message text comes from discussion.messages. A restricted workflow session can always call Plain’s read operations. See Add a Sidekick Agent action.